home *** CD-ROM | disk | FTP | other *** search
/ Atari Mega Archive 1 / Atari Mega Archive - Volume 1.iso / language / gemfst18.lzh / GEMFAST.DOC < prev    next >
Text File  |  1992-12-06  |  257KB  |  6,931 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.                                     GemFast v1.8
  28.  
  29.                         Public Domain GEM Programming Library
  30.                                     By Ian Lepore
  31.          
  32.         
  33.                                   Reference Manual
  34.         
  35.         
  36.         
  37.         
  38.         
  39.         
  40.         
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.        Contents
  72.  
  73.        Introduction  . . . . . . . . . . . . . . . . . . . . . . . . . .    1
  74.           Quick Start Info . . . . . . . . . . . . . . . . . . . . . . .    1
  75.           Using this document  . . . . . . . . . . . . . . . . . . . . .    1
  76.           Begging for money  . . . . . . . . . . . . . . . . . . . . . .    2
  77.           Support  . . . . . . . . . . . . . . . . . . . . . . . . . . .    3
  78.  
  79.        Function Quick-Reference  . . . . . . . . . . . . . . . . . . . .    4
  80.  
  81.        Global Variables  . . . . . . . . . . . . . . . . . . . . . . . .    6
  82.           global[] . . . . . . . . . . . . . . . . . . . . . . . . . . .    6
  83.           gl_apversion . . . . . . . . . . . . . . . . . . . . . . . . .    6
  84.           gl_apcount . . . . . . . . . . . . . . . . . . . . . . . . . .    6
  85.           gl_apid  . . . . . . . . . . . . . . . . . . . . . . . . . . .    6
  86.           gl_apprivate . . . . . . . . . . . . . . . . . . . . . . . . .    6
  87.           gl_apptree . . . . . . . . . . . . . . . . . . . . . . . . . .    6
  88.           gl_ap1resv . . . . . . . . . . . . . . . . . . . . . . . . . .    6
  89.           gl_aprshdr . . . . . . . . . . . . . . . . . . . . . . . . . .    6
  90.           gl_ap2resv . . . . . . . . . . . . . . . . . . . . . . . . . .    6
  91.           gl_grfhandle . . . . . . . . . . . . . . . . . . . . . . . . .    6
  92.           gl_wchar . . . . . . . . . . . . . . . . . . . . . . . . . . .    6
  93.           gl_hchar . . . . . . . . . . . . . . . . . . . . . . . . . . .    6
  94.           gl_wbox  . . . . . . . . . . . . . . . . . . . . . . . . . . .    6
  95.           gl_hbox  . . . . . . . . . . . . . . . . . . . . . . . . . . .    6
  96.           gl_rwdesk  . . . . . . . . . . . . . . . . . . . . . . . . . .    6
  97.           gl_rfscrn  . . . . . . . . . . . . . . . . . . . . . . . . . .    6
  98.           gl_vwout . . . . . . . . . . . . . . . . . . . . . . . . . . .    6
  99.           gl_vxout . . . . . . . . . . . . . . . . . . . . . . . . . . .    6
  100.  
  101.        Application Library . . . . . . . . . . . . . . . . . . . . . . .    8
  102.           apl_cleanup  . . . . . . . . . . . . . . . . . . . . . . . . .    8
  103.           apl_mmvectors  . . . . . . . . . . . . . . . . . . . . . . . .    9
  104.           apl_vclose . . . . . . . . . . . . . . . . . . . . . . . . . .   10
  105.           apl_vopen  . . . . . . . . . . . . . . . . . . . . . . . . . .   10
  106.           apl_vshared  . . . . . . . . . . . . . . . . . . . . . . . . .   11
  107.           apl_xexit  . . . . . . . . . . . . . . . . . . . . . . . . . .   12
  108.           appl_exit  . . . . . . . . . . . . . . . . . . . . . . . . . .   12
  109.           apl_xinit  . . . . . . . . . . . . . . . . . . . . . . . . . .   12
  110.           appl_init  . . . . . . . . . . . . . . . . . . . . . . . . . .   12
  111.  
  112.        Error Message Library . . . . . . . . . . . . . . . . . . . . . .   14
  113.           exterror . . . . . . . . . . . . . . . . . . . . . . . . . . .   14
  114.           exterrset  . . . . . . . . . . . . . . . . . . . . . . . . . .   15
  115.  
  116.        Forms and Dialogs Library . . . . . . . . . . . . . . . . . . . .   17
  117.           Summary of Dialog Functions  . . . . . . . . . . . . . . . . .   17
  118.           Dialog Processing Options  . . . . . . . . . . . . . . . . . .   18
  119.              Basic Dialog Options  . . . . . . . . . . . . . . . . . . .   19
  120.              Dynamic Dialog Options  . . . . . . . . . . . . . . . . . .   20
  121.              Dynamic Dialog Defaults . . . . . . . . . . . . . . . . . .   21
  122.           frm_confine  . . . . . . . . . . . . . . . . . . . . . . . . .   21
  123.           frm_defaults . . . . . . . . . . . . . . . . . . . . . . . . .   22
  124.           frm_desktop  . . . . . . . . . . . . . . . . . . . . . . . . .   22
  125.  
  126.        
  127.        ======================================================================
  128.        GemFast v1.8                                                    Page i
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.           frm_dialog . . . . . . . . . . . . . . . . . . . . . . . . . .   24
  138.           frm_dsdial . . . . . . . . . . . . . . . . . . . . . . . . . .   26
  139.           frm_dsdialog . . . . . . . . . . . . . . . . . . . . . . . . .   26
  140.           frm_eflag  . . . . . . . . . . . . . . . . . . . . . . . . . .   28
  141.           frm_enableblit . . . . . . . . . . . . . . . . . . . . . . . .   30
  142.           frm_error  . . . . . . . . . . . . . . . . . . . . . . . . . .   30
  143.           frm_menu . . . . . . . . . . . . . . . . . . . . . . . . . . .   32
  144.           frm_mkmoveable . . . . . . . . . . . . . . . . . . . . . . . .   34
  145.           frm_nldialog . . . . . . . . . . . . . . . . . . . . . . . . .   35
  146.           frm_nlmenu . . . . . . . . . . . . . . . . . . . . . . . . . .   36
  147.           frm_printf . . . . . . . . . . . . . . . . . . . . . . . . . .   37
  148.           frm_progress . . . . . . . . . . . . . . . . . . . . . . . . .   38
  149.           frm_qchoice  . . . . . . . . . . . . . . . . . . . . . . . . .   41
  150.           frm_qerror . . . . . . . . . . . . . . . . . . . . . . . . . .   41
  151.           frm_qmenu  . . . . . . . . . . . . . . . . . . . . . . . . . .   42
  152.           frm_qtext  . . . . . . . . . . . . . . . . . . . . . . . . . .   43
  153.           frm_question . . . . . . . . . . . . . . . . . . . . . . . . .   43
  154.           frm_sizes  . . . . . . . . . . . . . . . . . . . . . . . . . .   44
  155.           frm_verror . . . . . . . . . . . . . . . . . . . . . . . . . .   45
  156.           frm_vprintf  . . . . . . . . . . . . . . . . . . . . . . . . .   45
  157.  
  158.        File Selector Library . . . . . . . . . . . . . . . . . . . . . .   46
  159.           fsel_exinput . . . . . . . . . . . . . . . . . . . . . . . . .   46
  160.           fsel_sminput . . . . . . . . . . . . . . . . . . . . . . . . .   46
  161.           fsl_dialog . . . . . . . . . . . . . . . . . . . . . . . . . .   47
  162.  
  163.        Graphics Library  . . . . . . . . . . . . . . . . . . . . . . . .   51
  164.           gra_qmstate  . . . . . . . . . . . . . . . . . . . . . . . . .   51
  165.           gra_qofmouse . . . . . . . . . . . . . . . . . . . . . . . . .   51
  166.           gra_qonmouse . . . . . . . . . . . . . . . . . . . . . . . . .   52
  167.           grf_blit . . . . . . . . . . . . . . . . . . . . . . . . . . .   52
  168.           grf_memblit  . . . . . . . . . . . . . . . . . . . . . . . . .   53
  169.           graf_mouse . . . . . . . . . . . . . . . . . . . . . . . . . .   54
  170.           grf_mouse  . . . . . . . . . . . . . . . . . . . . . . . . . .   54
  171.  
  172.        Menu Library  . . . . . . . . . . . . . . . . . . . . . . . . . .   57
  173.           menu_bar . . . . . . . . . . . . . . . . . . . . . . . . . . .   57
  174.           mnu_bar  . . . . . . . . . . . . . . . . . . . . . . . . . . .   57
  175.           mnu_disable  . . . . . . . . . . . . . . . . . . . . . . . . .   58
  176.           mnu_enable . . . . . . . . . . . . . . . . . . . . . . . . . .   58
  177.           mnu_erase  . . . . . . . . . . . . . . . . . . . . . . . . . .   59
  178.           mnu_tbar . . . . . . . . . . . . . . . . . . . . . . . . . . .   59
  179.  
  180.        Object Library  . . . . . . . . . . . . . . . . . . . . . . . . .   61
  181.           obj_bmbuttons  . . . . . . . . . . . . . . . . . . . . . . . .   61
  182.           obj_clcalc . . . . . . . . . . . . . . . . . . . . . . . . . .   64
  183.           obj_flchange . . . . . . . . . . . . . . . . . . . . . . . . .   65
  184.           obj_mkthermo . . . . . . . . . . . . . . . . . . . . . . . . .   66
  185.           obj_mxuserdef  . . . . . . . . . . . . . . . . . . . . . . . .   68
  186.           obj_offxywh  . . . . . . . . . . . . . . . . . . . . . . . . .   70
  187.           obj_parent . . . . . . . . . . . . . . . . . . . . . . . . . .   70
  188.           obj_ppstring . . . . . . . . . . . . . . . . . . . . . . . . .   71
  189.           obj_rbfind . . . . . . . . . . . . . . . . . . . . . . . . . .   71
  190.           obj_rbselect . . . . . . . . . . . . . . . . . . . . . . . . .   72
  191.  
  192.        
  193.        ======================================================================
  194.        GemFast v1.8                                                   Page ii
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.           obj_stchange . . . . . . . . . . . . . . . . . . . . . . . . .   73
  204.           obj_udthermo . . . . . . . . . . . . . . . . . . . . . . . . .   74
  205.           obj_xtfind . . . . . . . . . . . . . . . . . . . . . . . . . .   75
  206.           obj_xywh . . . . . . . . . . . . . . . . . . . . . . . . . . .   76
  207.  
  208.        Rectangle Calulations Library . . . . . . . . . . . . . . . . . .   77
  209.           rc_confine . . . . . . . . . . . . . . . . . . . . . . . . . .   77
  210.           rc_copy  . . . . . . . . . . . . . . . . . . . . . . . . . . .   78
  211.           rc_equal . . . . . . . . . . . . . . . . . . . . . . . . . . .   78
  212.           rc_gadjust . . . . . . . . . . . . . . . . . . . . . . . . . .   79
  213.           rc_gtov  . . . . . . . . . . . . . . . . . . . . . . . . . . .   80
  214.           rc_intersect . . . . . . . . . . . . . . . . . . . . . . . . .   80
  215.           rc_ptinrect  . . . . . . . . . . . . . . . . . . . . . . . . .   81
  216.           rc_scale . . . . . . . . . . . . . . . . . . . . . . . . . . .   82
  217.           rc_union . . . . . . . . . . . . . . . . . . . . . . . . . . .   83
  218.           rc_vadjust . . . . . . . . . . . . . . . . . . . . . . . . . .   83
  219.           rc_vtog  . . . . . . . . . . . . . . . . . . . . . . . . . . .   84
  220.  
  221.        Resource Library  . . . . . . . . . . . . . . . . . . . . . . . .   85
  222.           rsc_cubuttons  . . . . . . . . . . . . . . . . . . . . . . . .   85
  223.           rsc_gstrings . . . . . . . . . . . . . . . . . . . . . . . . .   86
  224.           rsc_gtrees . . . . . . . . . . . . . . . . . . . . . . . . . .   88
  225.           rsc_rrbuttons  . . . . . . . . . . . . . . . . . . . . . . . .   89
  226.           rsc_sstrings . . . . . . . . . . . . . . . . . . . . . . . . .   90
  227.           rsc_sxtypes  . . . . . . . . . . . . . . . . . . . . . . . . .   91
  228.           rsc_treefix  . . . . . . . . . . . . . . . . . . . . . . . . .   92
  229.  
  230.        Window Library  . . . . . . . . . . . . . . . . . . . . . . . . .   93
  231.           wnd_top  . . . . . . . . . . . . . . . . . . . . . . . . . . .   93
  232.           wind_update  . . . . . . . . . . . . . . . . . . . . . . . . .   93
  233.           wnd_update . . . . . . . . . . . . . . . . . . . . . . . . . .   93
  234.  
  235.        Extended Binding Functions  . . . . . . . . . . . . . . . . . . .   95
  236.           evnx_multi . . . . . . . . . . . . . . . . . . . . . . . . . .   95
  237.           frmx_center  . . . . . . . . . . . . . . . . . . . . . . . . .   96
  238.           frmx_dial  . . . . . . . . . . . . . . . . . . . . . . . . . .   97
  239.           grfx_dragbox . . . . . . . . . . . . . . . . . . . . . . . . .   97
  240.           winx_calc  . . . . . . . . . . . . . . . . . . . . . . . . . .   98
  241.           winx_get . . . . . . . . . . . . . . . . . . . . . . . . . . .   99
  242.  
  243.        Extended VDI Functions  . . . . . . . . . . . . . . . . . . . . .  100
  244.           vdicall  . . . . . . . . . . . . . . . . . . . . . . . . . . .  100
  245.           vgd_detect . . . . . . . . . . . . . . . . . . . . . . . . . .  100
  246.           v_gchar  . . . . . . . . . . . . . . . . . . . . . . . . . . .  101
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.        
  259.        ======================================================================
  260.        GemFast v1.8                                                  Page iii
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.        Introduction
  270.  
  271.  
  272.                  Welcome to version 1.8 of GemFast, the public domain GEM
  273.                  bindings and programming library.  There are a lot of
  274.                  changes in v1.8, both in the libraries and in the
  275.                  documentation.  
  276.  
  277.                  The libraries have more high-level functions in them, and
  278.                  they pave the way for interesting things to come in the next
  279.                  couple of versions.
  280.  
  281.                  The documentation has been completely rewritten for v1.8. 
  282.                  I've tried to bring it up to the standards expected of
  283.                  professional programming manuals.  You'll still find a few
  284.                  first-person references in the function descriptions (mostly
  285.                  me apologizing for past blunders).  There are also places
  286.                  where I lapse into tutorial discussions of obscure GEM
  287.                  features.  This is mostly because there's not much point in
  288.                  my providing obscure functions without providing some
  289.                  description of the obscure features they support. ::grin::
  290.  
  291.  
  292.             Quick Start Info
  293.  
  294.  
  295.                  Because you generally only need it once, the installation
  296.                  instructions, packing list, technical notes, and portability
  297.                  notes are in a separate file called GEMFINST.DOC.  
  298.  
  299.                  If you're installing for the first time, GEMFINST.DOC has
  300.                  all the info you need to install the GemFast files on your
  301.                  system.  If you got GemFast along with the HSC compiler, the
  302.                  INSTALL program has already installed GemFast for you, but
  303.                  you should still review GEMFINST.DOC.
  304.  
  305.                  If you're upgrading from a prior release, you'll find the
  306.                  installation process pretty much the same as usual, but
  307.                  you'll want to pay special attention to some of the warnings
  308.                  in GEMFINST.DOC about the need to recompile your existing
  309.                  code.  If you don't follow instructions carefully, nothing
  310.                  will work right in the new library functions.
  311.  
  312.  
  313.             Using this document
  314.  
  315.  
  316.                  This document, as delivered, is formatted for printing on
  317.                  virtually any printer.  The format is a compromise between
  318.                  one that prints reasonably well on any type of printer, and
  319.                  one that is easy to browse interactively with an editor. 
  320.                  The original document is formatted very nicely indeed, in WP
  321.                  5.1 (MSDOS) format.  I'll distribute that version too, if
  322.                  anyone asks for it.
  323.  
  324.        
  325.        ======================================================================
  326.        GemFast v1.8                                                    Page 1
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.                  Here are some hints for online viewing...  If you're looking
  336.                  for a particular function, do a search on its name.  You'll
  337.                  find the entry in the table of contents.  If you just need a
  338.                  reminder of the function parameters, do a 'repeat search',
  339.                  and you'll find the prototype in the Quick Reference
  340.                  chapter.  If you want the full details of for the function,
  341.                  note the page number when you find the function in the table
  342.                  of contents, then do a search for "Page ##" to get near the
  343.                  function.  Then back up a few lines (page numbers are at the
  344.                  bottom of each page) to find the function.
  345.  
  346.                  This rather complex search-for-the-page-number nonsense is
  347.                  needed because the function descriptions include cross
  348.                  references and you could end up doing 20 or 30 'repeat
  349.                  search' operations on the function name to get to the actual
  350.                  description.  I hope to write a hypertext-like browser
  351.                  accessory for these docs soon to make this problem go away.
  352.  
  353.                  In the function descriptions, the last item is always a line
  354.                  stating where the source code for the file is found. 
  355.                  Because function descriptions cross page boundaries, be sure
  356.                  to keep reading until you hit the Source: line.
  357.  
  358.  
  359.             Begging for money
  360.  
  361.  
  362.                  Yes, after almost five years of distributing GemFast with no
  363.                  strings attached, I've suddenly become mercenary.  It has
  364.                  something to do with being unemployed at the moment. 
  365.  
  366.                  If you like GemFast, and you feel generous, please send a
  367.                  contribution of $15 to the name and address listed under
  368.                  Support, below.  Please do not send currency in the mail, it
  369.                  encourages crime.  If you are outside of the U.S.A., please
  370.                  don't feel obligated to send a contribution; it's more
  371.                  trouble than it's worth for you folks to get a check payable
  372.                  in US funds.
  373.  
  374.                  Despite my begging for contributions, GemFast is not
  375.                  shareware, it is public domain.  Here's the deal...
  376.  
  377.                    - GemFast v1.8 is 100% Public Domain.  I hereby explicitly
  378.                      release all rights to GemFast v1.8; you can use and
  379.                      distribute the source and binary in any way you like.  
  380.  
  381.                    - Programs developed with GemFast can be copyrighted by
  382.                      you or another party as you see fit; my release of
  383.                      rights to GemFast is not to be construed as a release of
  384.                      rights for any work which contains GemFast functions.
  385.  
  386.                    - Please keep the distribution archives completely intact
  387.                      when copying GemFast to other BBS systems.  If you've
  388.                      used GemFast as the GEM support for a compiler, you can
  389.  
  390.        
  391.        ======================================================================
  392.        GemFast v1.8                                                    Page 2
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.                      package the files with your compiler as you wish.  (IE,
  402.                      if you're just copying the standard distribution, please
  403.                      do it my way.  If you've repackaged as part of a larger
  404.                      work under another name, do it however you want.)
  405.  
  406.  
  407.             Support
  408.  
  409.  
  410.                  I love to hear from you, but I don't promise personalized
  411.                  replies.  I do take seriously all input I get on GemFast. 
  412.                  (Version 1.8 happened because of a nice letter I got from a
  413.                  gentleman in England, reporting some VDI bugs.  I fixed the
  414.                  bugs, and then sort of "got into it" and wrote about 20 new
  415.                  functions for the aes library.)
  416.  
  417.                  The files AESVRSN.DOC and VDIVRSN.DOC contain cumulative
  418.                  revision notes.  If you had only reported it, *your*
  419.                  favorite bug or enhancement might have been listed there.
  420.  
  421.                  Please don't hesitate to send me bug reports, suggestions
  422.                  for enhancements, or code you've written.  Look through your
  423.                  existing programs...if there are functions that show up in a
  424.                  lot of them, chances are they'd be at home in the GemFast
  425.                  libraries, so send them along.  A $15 contribution won't be
  426.                  refused either.  
  427.  
  428.                  I can be reached on the BIX online system, as "ianl".  On
  429.                  the internet, I can be reached at ilepore@nyx.cs.du.edu. 
  430.                  You can also reach me by snail-mail, at:
  431.  
  432.                      Ian Lepore
  433.                      6762 Marshall St.
  434.                      Arvada, CO  80003-4030
  435.                      USA
  436.  
  437.                  I probably won't reply by snail-mail, because my printer is
  438.                  broken (and there's not a chance of my writing a letter
  439.                  longhand).  If you reach me electronically, I'll generally
  440.                  reply within a few days.
  441.  
  442.                  - Ian Lepore
  443.                    11/03/92
  444.                    ilepore@nyx.cs.du.edu
  445.                    Moderator, BIX atari.st and c.language conferences
  446.                    Independant Software Developer (read: unemployed)
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.        
  457.        ======================================================================
  458.        GemFast v1.8                                                    Page 3
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.        Function Quick-Reference
  468.  
  469.  
  470.                  If you're like me, half the times you look at a library doc
  471.                  it's because you've forgotten what order the parms are in
  472.                  for some function.  Here's a list of prototypes for all
  473.                  functions.  Full descriptions of each function can be found
  474.                  in later chapters.
  475.  
  476.        void   apl_cleanup(int cleanup_type);
  477.        void   apl_mmvectors(void *allocfunc, void *freefunc);
  478.        void   apl_vclose(int vhandle);
  479.        int    apl_vopen(void);
  480.        int    apl_vshared(void);
  481.        void   apl_xexit(void);
  482.        int    apl_xinit(void);
  483.        char  *exterror(int errcode);
  484.        int    exterrset(_Err_tab *msgtab, int install_or_remove);
  485.        void   frm_confine(OBJECT *tree, GRECT *boundrect);
  486.        long   frm_defaults(long options);
  487.        void   frm_desktop(long options, OBJECT *tree);
  488.        int    frm_dialog(long options, OBJECT *tree, int editobj);
  489.        int    frm_dsdialog(long options, char **btnarray, char **strarray);
  490.        int    frm_dsmenu(long options, char *title, char **itemarray);
  491.        int    frm_eflag(OBJECT *tree, int object, char *fmt, ...);
  492.        void   frm_enableblit(void);
  493.        int    frm_error(int errcode, char *buttons, char *fmt, ...);
  494.        int    frm_menu(long options, OBJECT *tree, int select_state);
  495.        int    frm_mkmoveable(OBJECT *tree, int mover_object);
  496.        int    frm_nldialog(long options, char *buttons, char *lines);
  497.        int    frm_nlmenu(long options, char *title, char *items);
  498.        int    frm_printf(long options, char *buttons, char *fmt, ...);
  499.        int    frm_progress(long options, int increments, char *abortbutton,
  500.                            char *fmt, ...);
  501.        int    frm_qchoice(char *buttons, char *fmt, ...);
  502.        int    frm_qerror(int error, char *fmt, ...);
  503.        int    frm_qmenu(char *title, char *selections);
  504.        void   frm_qtext(char *fmt, ...);
  505.        int    frm_question(char *fmt, ...);
  506.        void   frm_sizes(OBJECT *tree, GRECT *outrect);
  507.        int    frm_verror(int errcode, char *buttons, char *fmt, 
  508.                          va_list args);
  509.        int    frm_vprintf(long options, char *buttons, char *fmt, 
  510.                           va_list args);
  511.        int    fsl_dialog(int options, char *opath, char *ipath, 
  512.                          char *forcewild, char *prompt);
  513.        long   grf_blit(int options, void *buffer, void *rect_or_tree);
  514.        void  *grf_memblit(int options, void *buffer, void *rect_or_tree);
  515.        int    grf_mouse(int newshape, void *usershape);
  516.        int    mnu_bar(OBJECT *tree, int install_or_remove, long reserved);
  517.        void   mnu_disable(void);
  518.        void   mnu_enable(void);
  519.  
  520.        void   mnu_erase(void);
  521.  
  522.        
  523.        ======================================================================
  524.        GemFast v1.8                                                    Page 4
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.        void   mnu_tbar(char *title_string);
  534.        int    obj_bmbuttons(OBJECT *tree, int parent, int select_state, 
  535.                             int bitmap);
  536.        int    obj_clcalc(OBJECT *tree, int object, GRECT *grectout, 
  537.                          VRECT *vrectout);
  538.        void   obj_flchange(OBJECT *tree, int object, int newstate, 
  539.                            int redraw, ...);
  540.        int    obj_mkthermo(OBJECT *tree, int object, int increments);
  541.        void   obj_offxywh(OBJECT *tree, int object, GRECT *outrect);
  542.        int    obj_parent(OBJECT *tree, int object);
  543.        char **obj_ppstring(OBJECT *pobj);
  544.        int    obj_rbfind(OBJECT *tree, int parent, int select_state);
  545.        int    obj_rbselect(OBJECT *tree, int object, int select_state);
  546.        void   obj_stchange(OBJECT *tree, int object, int new_state, 
  547.                            int redraw, ...);
  548.        int    obj_udthermo(OBJECT *tree, int object, int newpos, 
  549.                            GRECT *cliprect);
  550.        int    obj_xtfind(OBJECT *tree, int parent, int select_state);
  551.        void   obj_xywh(OBJECT *tree, int object, GRECT *outrect);
  552.        void   rc_confine(GRECT *boundrect, GRECT *therect);
  553.        void   rc_copy(GRECT *source, GRECT *dest);
  554.        int    rc_equal(GRECT *rect1, GRECT *rect1);
  555.        GRECT *rc_gadjust(GRECT *dest, int hadjust, int vadjust);
  556.        VRECT *rc_gtov(GRECT *source, VRECT *dest);
  557.        int    rc_intersect(GRECT *source, GRECT *dest);
  558.        int    rc_ptinrect(GRECT *therect, int x, int y);
  559.        GRECT *rc_scale(GRECT *source, GRECT *dest, int percentage);
  560.        void   rc_union(GRECT *source, GRECT *dest);
  561.        VRECT *rc_vadjust(VRECT *dest, int hadjust, int vadjust);
  562.        GRECT *rc_vtog(VRECT *source, GRECT *dest);
  563.        int    rsc_cubuttons(OBJECT *tree);
  564.        void   rsc_gstrings(OBJECT *tree, int object, char **ppstring, ...);
  565.        void   rsc_gtrees(int object, OBJECT **pptree, ...);
  566.        int    rsc_rrbuttons(OBJECT *tree);
  567.        void   rsc_sstrings(OBJECT *tree, int object, char *string, ...);
  568.        void   rsc_sxtypes(OBJECT *tree, int object, int xtype, ...);
  569.        void   rsc_treefix(OBJECT *tree);
  570.        int    wnd_top(void);
  571.        int    wnd_update(int semaphore);
  572.  
  573.        int    evnx_multi(XMULTI *xm);
  574.        int    frmx_center(OBJECT *tree, GRECT *outrect);
  575.        int    frmx_dial(int flag, GRECT *little, GRECT *big);
  576.        int    grfx_dragbox(GRECT *start, GRECT *boundary, GRECT *end);
  577.        int    winx_calc(int type, int kind, GRECT inrect, GRECT *outrect);
  578.        int    winx_get(int whandle, int field, GRECT *outrect);
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.        
  589.        ======================================================================
  590.        GemFast v1.8                                                    Page 5
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.        Global Variables
  600.  
  601.  
  602.                  GemFast provides several global variables containing
  603.                  information about the state of the system and your
  604.                  application.  The GEMFAST.H header file declares all these
  605.                  variables; you can just refer to them as needed in your
  606.                  programs.  A summary of the variables appears below,
  607.                  followed by detailed information about them.
  608.  
  609.                  The following variables are defined by GEM:   
  610.  
  611.                    int    global[];      aliased by following names...
  612.                    int    gl_apversion;  the AES version number
  613.                    int    gl_apcount;    max # of concurrent AES applications
  614.                    int    gl_apid;       id of the current application
  615.                    long   gl_apprivate;  anything application wants to store 
  616.                    void  *gl_apptree;    pointer to array of object tree ptrs
  617.                    long   gl_ap1resv;    old name for pointer to rsc data
  618.                    RSHDR *gl_aprshdr;    pointer to head of rsc data
  619.                    int    gl_ap2resv[6]; unused entries in global array
  620.  
  621.                  The following variables are defined by GemFast:
  622.  
  623.                    int    gl_grfhandle;  physical VDI workstation handle 
  624.                    int    gl_wchar;      width of a character
  625.                    int    gl_hchar;      height of a character
  626.                    int    gl_wbox;       width of a boxchar
  627.                    int    gl_hbox;       height of a boxchar
  628.                    GRECT  gl_rwdesk;     coordinates of the desktop workarea
  629.                    GRECT  gl_rfscrn;     coordinates of the full screen
  630.  
  631.                  The following variables are valid only after one or more
  632.                  calls have been made to apl_vopen() or apl_vshared():
  633.  
  634.                    int    gl_vwout[57];  the work_out from v_opnvwk()
  635.                    int    gl_vxout[57];  the work_out from vq_extnd(,1,)
  636.  
  637.                  The GEM-defined variables are documented in any manual or
  638.                  textbook on GEM programming.  The gl_ names in this group
  639.                  are just aliases for the items in the global array.  (That
  640.                  is, gl_apversion is just another name for global[0], etc.)
  641.  
  642.                  The GemFast-defined variables contain data that many GemFast
  643.                  library routines (and GEM programs in general) need frequent
  644.                  access to.  You can refer to these values in your code any
  645.                  time after you've called appl_init().  The values in these
  646.                  variables will never change, and you must never change them;
  647.                  they are for reference only.
  648.  
  649.                  The gl_grfhandle variable contains the physical VDI
  650.                  workstation handle owned by the AES.  This is the value
  651.                  returned by graf_handle().  You should never use this handle
  652.                  directly in your VDI calls; the only proper use is to pass
  653.  
  654.        
  655.        ======================================================================
  656.        GemFast v1.8                                                    Page 6
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.                  this value to VDI when opening a virtual screen workstation.
  666.  
  667.                  The gl_wchar, gl_hchar, gl_wbox, and gl_hbox variables
  668.                  contain the sizes of a character and a box that will hold a
  669.                  character.  These are the values returned by graf_handle(). 
  670.                  They are very useful values, please use them whenever you
  671.                  can instead of hard-coding size constants (which may be
  672.                  wrong when alternate monitors are in use).
  673.  
  674.                  The gl_rwdesk structure contains the xywh values that
  675.                  describe the work area of the desktop (everything on the
  676.                  screen except the menu bar area, generally).  The gl_rfscrn
  677.                  structure contains the xywh values that describe the full
  678.                  screen.  These values can be handy for clipping and
  679.                  confining operations; just pass their address (don't forget
  680.                  the '&' character!) to the rectangle calculation functions
  681.                  as needed.
  682.  
  683.                  The gl_vwout array contains the values that v_opnvwk() puts
  684.                  into the work_out array.  The gl_vxout array contains the
  685.                  values from vq_extnd(handle, 1, gl_vxout).  The values in
  686.                  these two arrays are valid only after you've opened a VDI
  687.                  workstation by calling apl_vopen().  These arrays are
  688.                  defined in a different module than the other global
  689.                  variables, and will only be linked into your program if you
  690.                  actually use VDI (or use a GemFast function which uses VDI).
  691.  
  692.                  Some of the variables are defined and initialized by GEM
  693.                  during the appl_init() call, and others are defined and
  694.                  initialized by GemFast during the apl_xinit() call.  A macro
  695.                  in GEMFAST.H remaps your existing appl_init() calls through
  696.                  the new apl_xinit().  Do NOT undo this mapping macro!  The
  697.                  GemFast library routines count on the data in the global
  698.                  variables being accurate, and that will only happen if
  699.                  control was passed through apl_xinit() on the way to the
  700.                  real GEM init function.
  701.  
  702.                  In general, I don't like global variables in C programs very
  703.                  much.  But, as the GemFast library routines became more
  704.                  complex, I found that every new routine was calling GEM to
  705.                  get the height of a character or the rectangle describing
  706.                  the system desktop or something.  It was getting to be a
  707.                  real performance problem.  So, I looked back through five
  708.                  years worth of programs I've written, and decided on a very
  709.                  small set of global variables to hold the information that
  710.                  most GEM programs seem to need.
  711.  
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.        
  721.        ======================================================================
  722.        GemFast v1.8                                                    Page 7
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.        Application Library
  732.  
  733.  
  734.                  Application library routines provide an interface between
  735.                  your program and the host environments that can supply
  736.                  services and resources to you.  Those hosts include GemFast
  737.                  itself, the GEM VDI and AES, and GEMDOS.  In general,
  738.                  application library routines help you manage system
  739.                  resources.
  740.  
  741.  
  742.  
  743.  
  744.        void    apl_cleanup(int options)
  745.        ______________________________________________________________________
  746.  
  747.        Summary:  Cleanup resources acquired internally by other library
  748.                  routines.
  749.  
  750.        Input:    The options parameter specifies the type of resources to
  751.                  clean up.  OR together any of the following:
  752.  
  753.                    APL_RTRANSIENT -  Temporary resources, such as the shared
  754.                                      VDI workstation.
  755.                    APL_RPERMANENT -  Permanent resources, such as attachments
  756.                                      to RSC data.
  757.  
  758.        Returns:  Nothing.
  759.  
  760.        See also: apl_xexit()
  761.  
  762.        Details:  Some library routines acquire system resources (VDI handle,
  763.                  blocks of memory, etc) in the course of processing.  This
  764.                  function releases those resources.  
  765.  
  766.                  This is intended primarily for desk accessories.  When an
  767.                  AC_CLOSE message is received, call this function with a 
  768.                  flag value of APL_RTRANSIENT.  If the desk accessory is
  769.                  going to unload itself, or has detected that a resolution
  770.                  change is happening, call this function with a flag value of
  771.                  (APL_RTRANSIENT | APL_RPERMANENT).
  772.  
  773.                  For a non-accessory program, a cleanup happens automatically
  774.                  when you call appl_exit(); you don't need to call
  775.                  apl_cleanup() explicitly.
  776.  
  777.                  Right now, the only transient resource is the shared VDI
  778.                  workstation, and there are no permanent resources.  That
  779.                  will change soon.
  780.  
  781.        Source:   aesfuncs\aplxinit.c
  782.  
  783.  
  784.  
  785.  
  786.        
  787.        ======================================================================
  788.        GemFast v1.8                                                    Page 8
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.        void    apl_mmvectors(void *allocfunc, void *freefunc)
  798.        ______________________________________________________________________
  799.  
  800.        Summary:  Specify the memory management routines for GemFast library
  801.                  functions to use when they need to allocate memory.
  802.  
  803.        Input:    The allocfunc parameter is a pointer to a memory allocation
  804.                  routine.
  805.  
  806.                  The freefunc parameter is a pointer to the memory free
  807.                  routine associated with the allocfunc allocation routine.
  808.  
  809.        Returns:  Nothing.
  810.  
  811.        See also:
  812.  
  813.        Details:  Some GemFast library routines need to allocate and free
  814.                  blocks of memory.  By default, the GEMDOS functions Malloc()
  815.                  and Mfree() are used.  The GEMDOS functions are not
  816.                  especially efficient, so this function lets you specify
  817.                  alternate memory management routines.
  818.  
  819.                  The most common use of this function will be to specify the
  820.                  names of your compiler's standard memory management
  821.                  functions.  The allocation function must accept a longword
  822.                  parameter and return a 32-bit pointer.  Often this function
  823.                  is called lalloc() or farmalloc() in your compiler library. 
  824.                  So the most common use would look like this:
  825.  
  826.                      apl_mmvectors(lalloc, free);
  827.  
  828.                  In general, you should probably use this function in .PRG
  829.                  programs, but not in desk accessories.  Compiler library
  830.                  memory management functions often allocate huge blocks of
  831.                  memory from GEMDOS, then subdivide the blocks internally. 
  832.                  This is Bad Behavior in a desk accessory, which shouldn't
  833.                  eat large chunks of memory unnecessarily.  
  834.  
  835.                  If you want to write your own memory management functions,
  836.                  here are some rules...  The allocator has to accept a
  837.                  longword size parameter, and return a 32-bit pointer.  It
  838.                  returns NULL if the memory can't be allocated.  The free
  839.                  function has to accept a 32-bit pointer; it returns nothing. 
  840.                  Do NOT write an 'intercept' allocator that accepts a
  841.                  longword size and passes it along to malloc() as a 16-bit
  842.                  value.  A huge moveable dialog box could occupy more than
  843.                  64k of screen memory on a high-resolution system.
  844.  
  845.        Source:   aesfuncs\aplmallo.c
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.        
  853.        ======================================================================
  854.        GemFast v1.8                                                    Page 9
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.        void    apl_vclose(int vdi_handle)
  864.        ______________________________________________________________________
  865.  
  866.        Summary:  Close a VDI workstation opened with apl_vopen().
  867.  
  868.        Input:    The vdi_handle parameter is a handle to a VDI virtual screen
  869.                  workstation.
  870.  
  871.        Returns:  Nothing.
  872.  
  873.        See Also: apl_vopen() apl_cleanup()
  874.  
  875.        Details:  This function closes a VDI workstation that was opened with
  876.                  a call to apl_vopen().  It will not close the shared
  877.                  workstation; only apl_cleanup() can close the shared
  878.                  workstation.
  879.  
  880.        Source:   aesfuncs\aplvwork.c
  881.  
  882.  
  883.  
  884.  
  885.        int     apl_vopen(void)
  886.        ______________________________________________________________________
  887.  
  888.        Summary:  Open a VDI virtual screen workstation.
  889.  
  890.        Input:    Nothing.
  891.  
  892.        Returns:  A VDI handle, or 0 if no handles are available.
  893.  
  894.        See Also: apl_vclose() 
  895.  
  896.        Details:  This function provides a simple way to open a VDI
  897.                  workstation.  It automatically handles the work_in and
  898.                  work_out arrays, and other basic details for you.  
  899.  
  900.                  The values from the work_out array are available in the
  901.                  global array gl_vwout any time after a VDI workstation
  902.                  (including the shared workstation) is opened.  The values
  903.                  returned by vq_extnd(,1) are also available in gl_vxout.
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.        
  919.        ======================================================================
  920.        GemFast v1.8                                                   Page 10
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.                  The work_in array is built automatically to set up the
  930.                  following default configuration:
  931.  
  932.                      static int work_in[11] = {
  933.                          -1, /* device driver (filled in at runtime) */
  934.                           1, /* polyline type    (normal)            */
  935.                           1, /* polyline color   (black)             */
  936.                           1, /* polymarker type  (dot)               */
  937.                           1, /* polymarker color (black)             */
  938.                           1, /* text face        (standard)          */
  939.                           1, /* text color       (black)             */
  940.                           1, /* fill interior    (solid)             */
  941.                           8, /* fill style       (solid)             */
  942.                           1, /* fill color       (black)             */
  943.                           2  /* use RC coordinate system             */
  944.                      }; 
  945.  
  946.                  After the workstation is open, you can change its attributes
  947.                  as you wish, using the vs_whatever() VDI functions.
  948.  
  949.        Source:   aesfuncs\aplvwork.c
  950.  
  951.  
  952.  
  953.  
  954.        int     apl_vshared(void)
  955.        ______________________________________________________________________
  956.  
  957.        Summary:  Returns the handle for the shared VDI workstation, opening
  958.                  the shared workstation if necessary.
  959.  
  960.        Input:    Nothing.
  961.  
  962.        Returns:  The handle of the shared VDI virtual screen workstation, or
  963.                  0 if no workstation is available.
  964.  
  965.        See Also: apl_vopen() apl_cleanup()
  966.  
  967.        Details:  This function opens the shared VDI workstation if it isn't
  968.                  open already, and returns the handle for it.
  969.  
  970.                  GemFast library routines need a lot VDI-based services,
  971.                  especially for blitting and custom object drawing.  Instead
  972.                  of having each routine open and close VDI workstations as
  973.                  needed, all routines now use the shared workstation.  Once
  974.                  the shared workstation is opened, it remains open from that
  975.                  point on.  (Unless you call apl_cleanup() to close it.)  If
  976.                  opened during the run of a program, appl_exit() closes it.
  977.  
  978.                  Your application can use the shared workstation for
  979.                  blitting, but I strongly recommend against using it for
  980.                  other VDI operations.  Any given library function could want
  981.                  the shared workstation, and it expects the attributes to be
  982.                  set to a standard configuration.  It would be difficult for
  983.  
  984.        
  985.        ======================================================================
  986.        GemFast v1.8                                                   Page 11
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.                  you determine whether it's "safe" to change the attributes
  996.                  at any given point to do some sort of output and then set
  997.                  them back.  The shared workstation can even get used by the
  998.                  AES itself, because some library routines install custom
  999.                  G_USERDEF drawing routines that get called by the AES
  1000.                  automatically.
  1001.  
  1002.        Source:   aesfuncs\aplvwork.c
  1003.  
  1004.  
  1005.  
  1006.  
  1007.        void    apl_xexit(void)
  1008.        void    appl_exit(void)
  1009.        ______________________________________________________________________
  1010.  
  1011.        Summary:  Cleanup acquired system resources, inform the AES that the
  1012.                  program is about to exit.
  1013.  
  1014.        NOTE:     A macro in GEMFAST.H remaps appl_exit to apl_xexit, so that
  1015.                  the extended exit function is automatically used when you
  1016.                  recompile your existing code.
  1017.  
  1018.        Input:    Nothing.
  1019.  
  1020.        Returns:  Nothing.
  1021.  
  1022.        See Also: apl_xinit() apl_cleanup()
  1023.  
  1024.        Details:  Currently, apl_xexit() just calls apl_cleanup() to release
  1025.                  permanent and transient resources, then it calls the real
  1026.                  appl_exit() function for you.  The primary purpose for the
  1027.                  extended exit function right now is to ensure that the
  1028.                  shared VDI workstation gets closed.  In the future, it'll do
  1029.                  more.
  1030.  
  1031.        Source:   aesfuncs\aplxinit.c
  1032.  
  1033.  
  1034.  
  1035.  
  1036.        int     apl_xinit(void)
  1037.        int     appl_init(void)
  1038.        ______________________________________________________________________
  1039.  
  1040.        Summary:  Register your application with the AES, and load values into
  1041.                  the GemFast-defined global variables.
  1042.  
  1043.        NOTE:     A macro in GEMFAST.H remaps appl_exit to apl_xexit, so that
  1044.                  the extended init function is automatically used when you
  1045.                  recompile your existing code.
  1046.  
  1047.        Input:    Nothing.
  1048.  
  1049.  
  1050.        
  1051.        ======================================================================
  1052.        GemFast v1.8                                                   Page 12
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.        Returns:  Application ID return by the AES, or a negative number if
  1062.                  the AES is not available.
  1063.  
  1064.        See Also: apl_xexit() 
  1065.  
  1066.        Details:  The extended init first calls the real appl_init() function. 
  1067.                  If that succeeds, it calls several inquiry functions to load
  1068.                  the global variables with data that most GEM programs need,
  1069.                  such as the sizes of the system desktop.  The chapter Global
  1070.                  Variables contains complete details on the global variables
  1071.                  initialized by this function.
  1072.  
  1073.        Source:   aesfuncs\aplxinit.c
  1074.  
  1075.  
  1076.  
  1077.  
  1078.  
  1079.  
  1080.  
  1081.  
  1082.  
  1083.  
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  
  1089.  
  1090.  
  1091.  
  1092.  
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098.  
  1099.  
  1100.  
  1101.  
  1102.  
  1103.  
  1104.  
  1105.  
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.  
  1114.  
  1115.  
  1116.        
  1117.        ======================================================================
  1118.        GemFast v1.8                                                   Page 13
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.        Error Message Library
  1128.  
  1129.  
  1130.                  The error message library contains several functions which
  1131.                  help support error reporting functions in the forms library. 
  1132.                  They are not, strictly speaking, GEM functions.  You may
  1133.                  find them useful even in your non-GEM programs.
  1134.  
  1135.                  The functions allow you to specify tables of error messages
  1136.                  and their associated error codes.  You can then report an
  1137.                  error message just by passing the code to frm_[q]error().
  1138.  
  1139.                  TOS reserves error codes in the range of -1 to -128.  Code 0
  1140.                  is, by convention, success.  Many compilers reserve a range
  1141.                  of codes for runtime library errors (HSC reserves -129
  1142.                  through -255 for this); consult your compiler documentation
  1143.                  for details.  Some compilers reserve a range of positive
  1144.                  rather than negative numbers.
  1145.  
  1146.                  I hereby declare that GemFast reserves codes in the range of
  1147.                  -15100 through -15199 for reporting GemFast internal errors. 
  1148.                  This seems like a small range in the middle of nowhere, and
  1149.                  shouldn't conflict with existing code.
  1150.  
  1151.  
  1152.  
  1153.  
  1154.        char *  exterror(int errcode)
  1155.        ______________________________________________________________________
  1156.  
  1157.        Summary:  Return a text description of the specified error code.
  1158.  
  1159.        Input:    The errcode parameter is the numeric error code you want the
  1160.                  text description of.
  1161.  
  1162.        Returns:  A pointer to a \0-terminated string describing the error. 
  1163.                  Do not modify the string this points to.  The return value
  1164.                  is guaranteed to be non-NULL, but it may point to an empty
  1165.                  string ("").
  1166.  
  1167.        NOTE:     You must code a #include "exterror.h" to use this function.
  1168.  
  1169.        See Also: exterrset() 
  1170.                  strerror()  (in your compiler's library)
  1171.  
  1172.        Details:  This function is similar to the strerror() function defined
  1173.                  by ANSI, except that it first searches tables of
  1174.                  application-specific error messages (installed by the
  1175.                  application using exterrset()).  If the application-specific
  1176.                  tables don't contain a message for the specified error
  1177.                  number, this function calls the standard strerror() function
  1178.                  to obtain the system-defined message.
  1179.  
  1180.                  This function can also deal with positive error codes, both
  1181.  
  1182.        
  1183.        ======================================================================
  1184.        GemFast v1.8                                                   Page 14
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.                  in the extended message tables and for strerror() if your
  1194.                  compiler's errno system uses positive error codes.
  1195.  
  1196.        Source:   aesfuncs\exterror.c
  1197.  
  1198.  
  1199.  
  1200.  
  1201.        int     exterrset(_Err_tab *ptab, int install_or_remove)
  1202.        ______________________________________________________________________
  1203.  
  1204.        Summary:  Installs or removes a table of application-specific error
  1205.                  codes and their associated messages.
  1206.  
  1207.        Input:    The ptab parameter is a pointer to an array of _Err_tab
  1208.                  structures coded in your application.  
  1209.  
  1210.                  The install_or_remove parameter is a flag indicating whether
  1211.                  the specified table is to be installed in the list of
  1212.                  extended message tables, or removed from that list.  A table
  1213.                  can be safely removed more than once.
  1214.  
  1215.        Returns:  0 on success, or -1 if there are no more slots available in
  1216.                  the extended tables list.
  1217.  
  1218.        NOTE:     You must code a #include "exterror.h" to use this function.
  1219.  
  1220.        See Also: exterror()
  1221.  
  1222.        Details:  This function installs or removes tables of application-
  1223.                  specific error messages.  The exterror() function returns
  1224.                  message from these tables.  You create extended message
  1225.                  tables by coding an array of _Err_tab structures and
  1226.                  initializing the array with your codes and messages.  The
  1227.                  _Err_tab structure is defined in EXTERROR.H, as follows:
  1228.  
  1229.                      typedef struct _Err_tab {
  1230.                          int   code;
  1231.                          char *msg;
  1232.                      } _Err_tab;
  1233.  
  1234.                  To create a table of extended messages, code an array and
  1235.                  initialize it with your errcode/msg pairs.  Use an error
  1236.                  code value of zero to indicate the end of the table.  You
  1237.                  can define any error code in the range of -32768 through
  1238.                  32767, excluding code 0.  If you provide messages for
  1239.                  system-defined error codes, exterror() finds your messages
  1240.                  first, and returns them instead of calling strerror().  In
  1241.                  other words, you can override the wording of system
  1242.                  messages.
  1243.  
  1244.  
  1245.  
  1246.  
  1247.  
  1248.        
  1249.        ======================================================================
  1250.        GemFast v1.8                                                   Page 15
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.        Example:  The following is an example of creating and installing an
  1260.                  extended error message table defining 3 application-specific
  1261.                  messages: 
  1262.  
  1263.                      static _Err_tab my_messages[] = {
  1264.                          {-300, "Input must be between 0 and 200"},
  1265.                          {-301, "Cannot locate configuration file"},
  1266.                          {-302, "Internal data corrupted"},
  1267.                          {0,    NULL};
  1268.  
  1269.                      exterrset(my_messages, TRUE);
  1270.  
  1271.                  Note that I don't check the return code from exterrset() in
  1272.                  the example.  You really should check it. ::grin::
  1273.  
  1274.                  The internal list is currently configured for up to 8
  1275.                  extended message tables.
  1276.  
  1277.        Source:   aesfuncs\exterror.c
  1278.  
  1279.  
  1280.  
  1281.  
  1282.  
  1283.  
  1284.  
  1285.  
  1286.  
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.  
  1302.  
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308.  
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.        
  1315.        ======================================================================
  1316.        GemFast v1.8                                                   Page 16
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.        Forms and Dialogs Library
  1326.  
  1327.  
  1328.                  The forms and dialogs library contains functions related to
  1329.                  dialog processing.  Some of the functions are designed to
  1330.                  help you conduct your own dialogs, and others invoke pre-
  1331.                  written dialogs using your parameters and messages.  
  1332.  
  1333.                  The pre-written dialogs use options and strings you specify,
  1334.                  and dynamically build and conduct a dialog based on them. 
  1335.                  For this reason, they are collectively referred to as the
  1336.                  'dynamic' dialogs.  The dynamic dialogs are divided into two
  1337.                  groups, the basic functions and the quick functions.  The
  1338.                  basic functions allow you to specify options and a variety
  1339.                  of exit buttons.  The quick functions are easy to call; they
  1340.                  provide default options and buttons.  (The quick functions
  1341.                  do not execute faster; they're quicker to code.)  The basic
  1342.                  dynamic dialogs exist primarily to support the higher-level
  1343.                  quick dialogs, but there's no reason you can't use them
  1344.                  directly if you need the extra options or buttons.
  1345.  
  1346.  
  1347.             Summary of Dialog Functions
  1348.  
  1349.  
  1350.                  The functions which help you conduct your own dialogs are:
  1351.  
  1352.                      frm_confine     Confines dialog to rectangular area.
  1353.                      frm_defaults    Sets default options.
  1354.                      frm_dialog      Conducts your standard dialog.
  1355.                      frm_menu        Conducts your menu (object tree) dialog.
  1356.                      frm_enableblit  Enables screen save/restore via blit.
  1357.                      frm_eflag       Reports error made by user in a dialog.
  1358.                      frm_mkmoveable  Makes your dialog moveable.
  1359.                      frm_desktop     Installs your custom desktop.
  1360.                      frm_sizes       Calculates dialog's on-screen sizes.
  1361.  
  1362.                  The basic dynamic dialogs are:
  1363.  
  1364.                      frm_dsdialog    Automatic text dialog - hard to use.
  1365.                      frm_nldialog    Automatic text dialog - easier to use.
  1366.                      frm_dsmenu      Automatic menu dialog - hard to use.
  1367.                      frm_nlmenu      Automatic menu dialog - easier to use.
  1368.                      frm_printf      Formatted text dialog, like printf().
  1369.                      frm_progress    Formatted progress display.
  1370.                      frm_error       Formatted error reporting.
  1371.                      frm_verror      Alternate form of frm_error.
  1372.                      frm_vprintf     Alternate form of frm_printf.
  1373.  
  1374.                  The quick dynamic dialogs are:
  1375.  
  1376.                      frm_qchoice     Formatted text and choice of 5 buttons.
  1377.                      frm_qerror      Formatted error reporting.
  1378.                      frm_qmenu       Automatic menu (like dropdown in a box).
  1379.  
  1380.        
  1381.        ======================================================================
  1382.        GemFast v1.8                                                   Page 17
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.                      frm_qtext       Formatted text display.
  1392.                      frm_question    Formatted yes/no question.
  1393.  
  1394.                  If you look in the GemFast source code, you may find some
  1395.                  other functions in the frm_ family.  Do NOT use any
  1396.                  functions not described in this document.  If it's not
  1397.                  documented here, I guarantee you the calling standard for it
  1398.                  will change in the next version, and your programs will
  1399.                  break.  If it wasn't in a state of flux, it'd be documented.
  1400.  
  1401.  
  1402.             Dialog Processing Options
  1403.  
  1404.  
  1405.                  At the root of all dialog processing in GemFast is the
  1406.                  frm_dialog() function.  All dynamic dialogs eventually end
  1407.                  up in it, including the menu dialogs.  You can also use it
  1408.                  for processing your custom application dialogs.  There are a
  1409.                  variety of options that frm_dialog() can act on for you. 
  1410.                  Several of the dynamic dialogs have options that apply
  1411.                  specifically to them, but not to dialog processing in
  1412.                  general.  All dialog processing options are listed below.  
  1413.  
  1414.                  In addition to options which control the appearance of a
  1415.                  dialog, some functions accept action flags which dictate the
  1416.                  steps or parts of a dialog to be performed.  This applies
  1417.                  primarily to the frm_dialog() function.  Because they are
  1418.                  specific to only a few of the functions, action flags are
  1419.                  described along with the function that uses them.
  1420.  
  1421.                  It makes sense for all dialogs in an application to behave
  1422.                  pretty much the same way, so GemFast provides the
  1423.                  frm_defaults() function to specify default dialog options. 
  1424.                  You can set the default options once, during program
  1425.                  startup, then use just FRM_NORMAL in all your dialog
  1426.                  function calls, and everything (including dynamic dialogs
  1427.                  which don't let you specify any options) will behave
  1428.                  according to the defaults you set.
  1429.  
  1430.                  The options parameter for all dialog library functions is a
  1431.                  longword.  It is important for you to use the constant
  1432.                  FRM_NORMAL instead of just 0 or NORMAL when you want no
  1433.                  special options.  Options are encoded in the longword as a
  1434.                  collection of bits.  The bits for different types of options
  1435.                  appear in distinct places in the longword (not that this
  1436.                  really has much affect on you in the current version) as
  1437.                  follows:
  1438.  
  1439.                      0xAUDDBBBB
  1440.                        ||| |______ Basic options for all dialog handling.
  1441.                        |||________ Dynamic dialog options.
  1442.                        ||_________ User options; never touched by GemFast.
  1443.                        |__________ Actions.
  1444.  
  1445.  
  1446.        
  1447.        ======================================================================
  1448.        GemFast v1.8                                                   Page 18
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.             Basic Dialog Options
  1458.  
  1459.  
  1460.                  The FRM_NORMAL option is really a placeholder that says you
  1461.                  want no options other than the defaults already established.
  1462.  
  1463.                  The FRM_EXPLODE option draws exploding-box graphics during
  1464.                  the start and finish phases of a dialog.  The small box for
  1465.                  the grow/shrink calls is one-fifth the size of the full
  1466.                  dialog, centered under the full dialog.
  1467.  
  1468.                  The FRM_MOUSEARROW option forces the mouse cursor shape to
  1469.                  an arrow for the duration of the dialog, then changes it
  1470.                  back to the prior shape when the user exits.
  1471.  
  1472.                  The FRM_CENTER option centers the dialog within the desktop
  1473.                  before drawing it.
  1474.  
  1475.                  The FRM_NEARMOUSE option centers the dialog over the current
  1476.                  mouse location (adjusting as necessary to keep the dialog
  1477.                  wholly on-screen) before drawing it.  FRM_NEARMOUSE takes
  1478.                  precedence over FRM_CENTER when both are specified.
  1479.  
  1480.                  The FRM_USEBLIT option saves and restores the screen under
  1481.                  the dialog using blits instead of redraw messages.  You must
  1482.                  call frm_enableblit() at least once before this option is
  1483.                  honored.  This option only has effect when the frm_dialog()
  1484.                  action flags are equal to FRM_DCOMPLETE (ie, when you're
  1485.                  doing all phases of the dialog in a single call).  The blit
  1486.                  buffer is allocated and freed by frm_dialog().  If the
  1487.                  allocation fails, the FRM_USEBLIT option is turned off for
  1488.                  the duration of that frm_dialog() call.
  1489.  
  1490.                  The FRM_MOVEABLE option designates the dialog as moveable
  1491.                  even if no object in the dialog has the FRM_MOVER bit on in
  1492.                  its ob_flags.  The FRM_USEBLIT option has to be in effect
  1493.                  for this option to function, and all conditions required for
  1494.                  FRM_USEBLIT to take effect apply to this option as well.  If
  1495.                  you have used frm_mkmoveable() to designate a specific mover
  1496.                  object within a dialog, this option has no effect; the mover
  1497.                  object will always move the dialog regardless of this
  1498.                  option.  If you specify this option for a dialog that has no
  1499.                  designated mover object, the root object becomes the dialog
  1500.                  mover automatically.  The basic point to this option is that
  1501.                  you can set it as the default, and all your dialogs suddenly
  1502.                  become moveable even when you haven't designed in a mover
  1503.                  object.  If allocation of a blit buffer fails, the dialog is
  1504.                  treated as unmovable.  When your dialogs stop moving, you're
  1505.                  getting low on memory.
  1506.  
  1507.                  The FRM_NODEFAULTS option can be passed to frm_dialog() or
  1508.                  the dynamic dialogs to disable the default options for that
  1509.                  specific call. When you pass FRM_NODEFAULTS as one of your
  1510.                  options, the default options are ignored, and only the
  1511.  
  1512.        
  1513.        ======================================================================
  1514.        GemFast v1.8                                                   Page 19
  1515.  
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523.                  options passed along with FRM_NODEFAULTS are used.
  1524.  
  1525.  
  1526.             Dynamic Dialog Options
  1527.  
  1528.  
  1529.                  The FRM_DMUSTSELECT option is interpreted based on the type
  1530.                  of dialog.  For a text dialog, it indicates that there is no
  1531.                  default exit button; the user "must select" a button with
  1532.                  the mouse.  For a menu dialog, it indicates that the user
  1533.                  must click on a selectable item; clicking outside the dialog
  1534.                  box does not end the dialog and return NO_OBJECT. 
  1535.  
  1536.                  The FRM_DSHADOWED option draws the parent box of the dynamic
  1537.                  dialog (text or menu) as a SHADOWED object instead of an
  1538.                  OUTLINED object.  
  1539.  
  1540.                  The FRM_MEXITPARENT option causes the menu dialog to return
  1541.                  NO_OBJECT as soon as the mouse leaves the dialog box.  This
  1542.                  option applies only to menu dialogs and has no effect on
  1543.                  text dialogs.
  1544.  
  1545.                  The FRM_MEXITVICINITY option cause the menu dialog to return
  1546.                  NO_OBJECT as soon as the mouse leaves the near vicinity of
  1547.                  the dialog box.  The vicinity is an area that extends four
  1548.                  character widths to either side of the dialog box and two
  1549.                  characters heights above and below it.  This option applies
  1550.                  only to menu dialogs and has no effect on text dialogs.
  1551.  
  1552.                  The MUSTSELECT option takes precedence over MEXITPARENT and
  1553.                  MEXITVICINITY.  When MUSTSELECT is specified, you are
  1554.                  guaranteed never to get a NO_OBJECT return value.
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.  
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.        
  1579.        ======================================================================
  1580.        GemFast v1.8                                                   Page 20
  1581.  
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.             Dynamic Dialog Defaults
  1590.  
  1591.  
  1592.                  For dynamic dialogs that allow you to specify a list of exit
  1593.                  buttons, a NULL button pointer gives you a single exit
  1594.                  button containing "Continue" as its text.  You also get a
  1595.                  Continue button for the quick dynamic dialogs that don't let
  1596.                  you specify a list of buttons.
  1597.  
  1598.                  While it's pretty pointless to do so, if you pass a NULL
  1599.                  pointer for the text string or format string describing the
  1600.                  body of the dialog, the body will be a single line
  1601.                  containing "<no message>".
  1602.  
  1603.                  All dynamic dialogs use a default internal options list. 
  1604.                  These automatic defaults are added to the options you set
  1605.                  with frm_defaults() and whatever you specify in the call. 
  1606.                  The automatic dynamic dialog defaults are:
  1607.  
  1608.                    (FRM_CENTER | FRM_USEBLIT | FRM_MOVEABLE | FRM_MOUSEARROW)
  1609.  
  1610.                  As usual, if you specify NEARMOUSE it takes precedence over
  1611.                  the default CENTER.  The USEBLIT and MOVEABLE defaults are
  1612.                  honored only if you've called frm_enableblit().  If you pass
  1613.                  FRM_NODEFAULTS to a dynamic dialog, the defaults listed
  1614.                  above are not used, only the options you specify in that
  1615.                  call are used.  An oddball exception is that if you specify
  1616.                  NODEFAULTS and don't include CENTER or NEARMOUSE, CENTER is
  1617.                  assumed (otherwise where would the dialog be placed?).
  1618.  
  1619.  
  1620.  
  1621.  
  1622.        void    frm_confine(OBJECT *ptree, GRECT *boundrect)
  1623.        ______________________________________________________________________
  1624.  
  1625.        Summary:  Adjust the location of an object tree so that it is confined
  1626.                  within a specified area.
  1627.  
  1628.        Input:    The ptree parameter is a pointer to the tree to adjust.
  1629.  
  1630.                  The boundrect parameter is a pointer to the rectangle in
  1631.                  which the tree is to be placed.
  1632.  
  1633.        Returns:  Nothing.
  1634.  
  1635.        See also: rc_confine()
  1636.  
  1637.  
  1638.  
  1639.  
  1640.  
  1641.  
  1642.  
  1643.  
  1644.        
  1645.        ======================================================================
  1646.        GemFast v1.8                                                   Page 21
  1647.  
  1648.  
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654.  
  1655.        Details:  This function adjusts the x/y values of the object tree as
  1656.                  needed to keep that tree within the specified rectangle.  It
  1657.                  never modifies the width or height of the tree; if the tree
  1658.                  will not wholly fit within the boundary rectangle, it is
  1659.                  aligned to the upper and left sides of the boundary as
  1660.                  needed.  This function takes OUTLINED and SHADOWED flags
  1661.                  into account, and makes sure the dialog is entirely within
  1662.                  the boundary, visually.
  1663.  
  1664.        Source:   aesfuncs\frmconfi.c
  1665.  
  1666.  
  1667.  
  1668.        long    frm_defaults(long options)
  1669.        ______________________________________________________________________
  1670.  
  1671.        Summary:  Get or set default dialog processing options.
  1672.  
  1673.        Input:    The options parameter specifies the new default options as a
  1674.                  bitmap; the available values are described under Dialog
  1675.                  Processing Options.  In addition, the following special
  1676.                  value may be passed instead of the standard options:
  1677.  
  1678.                    FRM_GETDEFAULTS - Return the current defaults without
  1679.                                      changing them.
  1680.  
  1681.        Returns:  The default options in effect before the call.
  1682.  
  1683.        See Also: frm_dialog()
  1684.  
  1685.        Details:  The dialog functions support a variety of processing
  1686.                  options.  You can pass options to most of them on each call. 
  1687.                  In addition, you can use this function to set default
  1688.                  options that will be used on every subsequent call to
  1689.                  frm_dialog() or a dynamic dialog.  The default options set
  1690.                  by this function will apply to any other library function
  1691.                  which lists frm_defaults() in its "See Also" section.
  1692.  
  1693.                  Library routines will NOT change the default options behind
  1694.                  your back.  Library routines calling frm_dialog() do NOT use
  1695.                  FRM_NODEFAULTS to override your preferences.
  1696.  
  1697.        Source:   aesfuncs\frmdialo.c
  1698.  
  1699.  
  1700.  
  1701.  
  1702.        void    frm_desktop(long options, OBJECT *ptree)
  1703.        ______________________________________________________________________
  1704.  
  1705.        Summary:  Installs or removes an object tree as the system desktop.
  1706.  
  1707.        Input:    The options parameter specifies the installation option, use
  1708.                  one of the following values:
  1709.  
  1710.        
  1711.        ======================================================================
  1712.        GemFast v1.8                                                   Page 22
  1713.  
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.  
  1721.                    FRM_NORMAL   -    No options; the tree is installed
  1722.                                      without any changes.
  1723.                    FRM_CENTER   -    The tree is automatically fitted to the
  1724.                                      desktop.  
  1725.  
  1726.                  The ptree parameter is a pointer to the object tree to
  1727.                  install as the new desktop.  When NULL, it indicates you are
  1728.                  removing any custom desktop you've previously installed.
  1729.  
  1730.        Returns:  Nothing.
  1731.  
  1732.        See Also:
  1733.  
  1734.        Details:  This function makes the specified object tree the new
  1735.                  desktop, for the duration of your program or until you
  1736.                  remove it with another call to this function.  Desk
  1737.                  accessories MUST NOT use this function.
  1738.  
  1739.                  The desktop is automatically repainted by the AES; it acts
  1740.                  as if the AES is running an evnt_multi() loop internally,
  1741.                  and responds to redraw messages for the desktop by calling
  1742.                  objc_draw() on the desktop tree.  The default system desktop
  1743.                  is a single G_BOX object with no borders or outline.
  1744.  
  1745.                  By installing your own dialog as the system desktop, you can
  1746.                  get the benefits of a windowed program without the hassle of
  1747.                  using window redraw logic in your program.  If your
  1748.                  application has a single main dialog box, you can install it
  1749.                  as the desktop and call other dialog functions -- even the
  1750.                  file selector -- and your main dialog is automatically
  1751.                  redrawn as other windows and dialogs are closed or moved.
  1752.  
  1753.                  After installing your tree as the desktop, this function
  1754.                  sends out redraw messages which cause it to be painted
  1755.                  automatically.  You never need to call objc_draw() to show
  1756.                  the tree.  If the tree is a dialog, just call form_do() (or
  1757.                  frm_dialog(FRM_DDO)) to start the dialog, and don't call
  1758.                  form_dial(FMD_FINISH) when you're done.
  1759.  
  1760.                  To use a dialog as the desktop, I recommend that you create
  1761.                  the main dialog box as a borderless non-outlined box filled
  1762.                  with solid green.   Make the second object in the tree a box
  1763.                  with an inside width of 2 and OUTLINED.  (IE, the second
  1764.                  object is a box just like the one used as the first object
  1765.                  in a normal dialog.)  Then call this function, passing an
  1766.                  option of FRM_CENTER.  The FRM_CENTER option causes this
  1767.                  function to automatically adjust the main box (the first
  1768.                  object) to be exactly the size of the system desktop, and
  1769.                  then it centers the second object (the actual dialog box)
  1770.                  within the desktop.  Visually, you get the effect of a
  1771.                  dialog that has been form_center'd on a regular desktop.
  1772.  
  1773.  
  1774.  
  1775.  
  1776.        
  1777.        ======================================================================
  1778.        GemFast v1.8                                                   Page 23
  1779.  
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787.                  If you don't use the FRM_CENTER option, you MUST ensure that
  1788.                  the first object in the tree is exactly the size of the
  1789.                  desktop.
  1790.  
  1791.                  When your desktop root object has been defined as a box
  1792.                  filled with a solid non-background color (eg, a standard
  1793.                  solid green desktop), this routine modifies the box to a 50%
  1794.                  gray fill when running on a monochrome system.  (Otherwise
  1795.                  the "solid green" box would appear as solid black on a
  1796.                  monochrome monitor.)  In other words, if you follow the
  1797.                  recommendation of designing a solid green desktop, this
  1798.                  routine automatically adjusts the desktop to match the
  1799.                  standard system desktop when running on monochrome monitors.
  1800.  
  1801.        Source:   aesfuncs\frmdeskt.c
  1802.  
  1803.  
  1804.  
  1805.  
  1806.        int     frm_dialog(long options, OBJECT *ptree, int startobj)
  1807.        ______________________________________________________________________
  1808.  
  1809.        Summary:  Conducts all or part of a dialog with the user.
  1810.  
  1811.        Input:    The options parameter specifies actions and options as a
  1812.                  bitmap; the available values are described under Dialog
  1813.                  Processing Options.  In addition to the options, any of the
  1814.                  following actions can be ORed into the parameter value:
  1815.  
  1816.                    FRM_DSTART     -  Do the FMD_START and FMD_GROW.
  1817.                    FRM_DDRAW      -  Do the objc_draw().
  1818.                    FRM_DDO        -  Do the form_do().
  1819.                    FRM_DFINISH    -  Do the FMD_SHRINK and FMD_FINISH.
  1820.                    FRM_DCOMPLETE  -  Do all of the above in one call.
  1821.  
  1822.                  If no actions are provided, FRM_DCOMPLETE is assumed.
  1823.  
  1824.                  The ptree parameter is a pointer to the dialog tree.
  1825.  
  1826.                  The startobj parameter is interpreted according the action
  1827.                  options.  If just FRM_DDRAW is requested, startobj is the
  1828.                  object to start drawing at.  If actions other than drawing
  1829.                  are also requested, the full object tree is drawn, and
  1830.                  startobj is the initial text edit object for form_do().
  1831.  
  1832.        Returns:  The index of the exit object.  Be aware that if the exit
  1833.                  object was a TOUCHEXIT, and the user double-clicked on it,
  1834.                  the high bit in the return value is set (making it look
  1835.                  negative).  If the exit object had the EXIT or DEFAULT bits
  1836.                  on in its ob_flags, it is automatically set to ~SELECTED,
  1837.                  both in the object structure, and visually on the screen.
  1838.  
  1839.        See Also: frm_enableblit() frm_defaults()
  1840.  
  1841.  
  1842.        
  1843.        ======================================================================
  1844.        GemFast v1.8                                                   Page 24
  1845.  
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.  
  1853.        Details:  The most frequent use of this function is really fairly
  1854.                  simple.  To conduct a complete interaction with a user, you
  1855.                  only need to code something like:
  1856.  
  1857.                     selection = frm_dialog(FRM_CENTER, mydialog, 0);
  1858.  
  1859.                  You can, of course, use any of the other options.  You can
  1860.                  also use this function to conduct a dialog "in pieces".  (A
  1861.                  disadvantage to this is that a dialog conducted in pieces
  1862.                  won't honor the USEBLIT and MOVEABLE options.)  Such a
  1863.                  sequence usually appears something like:
  1864.  
  1865.                    - Start dialog using frm_dialog(FRM_DSTART|FRM_DDRAW).
  1866.                    - Loop:
  1867.                    -     Conduct interaction using frm_dialog(FRM_DDO).
  1868.                    -     Validate user's actions, if any errors are found,
  1869.                          use frm_eflag() to report them.
  1870.                    -     When the validations are good, exit the loop.
  1871.                    - Close dialog using frm_dialog(FRM_DFINISH).
  1872.  
  1873.                  When you're processing a dialog in pieces, it can be
  1874.                  important to know which options are processed during which
  1875.                  pieces of the dialog.  Processing occurs in several phases:
  1876.  
  1877.                    setup       - 1.  Call wnd_update(BEG_UPDATE).  
  1878.                                  2.  If FRM_USEBLIT is set, ensure that
  1879.                                      frm_enableblit() has been called and
  1880.                                      that FRM_DCOMPLETE was specified. 
  1881.                                      Ensure that a blit buffer is available. 
  1882.                                      If any of those are false, turn off
  1883.                                      FRM_USEBLIT.  
  1884.                                  3.  If the dialog contains an object flagged
  1885.                                      as the FRM_MOVER object, set
  1886.                                      FRM_MOVEABLE on.  
  1887.                                  4.  If FRM_MOVEABLE has been set, ensure
  1888.                                      that FRM_USEBLIT is in effect.  If there
  1889.                                      isn't an FRM_MOVER object, make the root
  1890.                                      object the mover.
  1891.  
  1892.                    FRM_DSTART  - 1.  Center the dialog on the desktop if
  1893.                                      FRM_CENTER is set, or center it over the
  1894.                                      mouse if FRM_NEARMOUSE is set.
  1895.                                  2.  Save the screen to the blit buffer if
  1896.                                      FRM_USEBLIT is set. Do the FMD_START,
  1897.                                      and if FRM_EXPLODE is set do the
  1898.                                      FMD_GROW.
  1899.  
  1900.                    FRM_DDRAW   -     Do the objc_draw().
  1901.  
  1902.                    FRM_DDO     - 1.  Change the mouse to an arrow if
  1903.                                      FRM_MOUSEARROW is set.  
  1904.                                  2.  Do the form_do().  If the exit object
  1905.                                      was the FRM_MOVER object, handle the
  1906.                                      dialog move, then loop back into
  1907.  
  1908.        
  1909.        ======================================================================
  1910.        GemFast v1.8                                                   Page 25
  1911.  
  1912.  
  1913.  
  1914.  
  1915.  
  1916.  
  1917.  
  1918.  
  1919.                                      form_do() again.
  1920.                                  3.  Reset the ob_state of the exit object to
  1921.                                      ~SELECTED, if it's an EXIT or DEFAULT
  1922.                                      object. 
  1923.                                  4.  Restore the mouse shape.
  1924.  
  1925.                    FRM_DFINISH - 1.  Do the FMD_SHRINK if FRM_EXPLODE is set. 
  1926.  
  1927.                                  2.  If FRM_USEBLIT is set, blit back the old
  1928.                                      screen contents, else do the FMD_FINISH
  1929.                                      to send out redraw messages.
  1930.  
  1931.                    cleanup      - 1. Free the blit buffer (if any).
  1932.                                   2. Call wnd_update(END_UPDATE).
  1933.  
  1934.                  The setup and cleanup phases are done on every call.  The
  1935.                  other phases are done when the corresponding action bit is
  1936.                  on in the options.
  1937.  
  1938.                  This function is fail-proof; if a blit buffer can't be
  1939.                  obtained, the dialog becomes unmovable, and redraw messages
  1940.                  are sent out after the dialog to restore the screen.  
  1941.  
  1942.        Source:   aesfuncs\frmdialo.c
  1943.  
  1944.  
  1945.  
  1946.  
  1947.        int     frm_dsdial(char **strings, char **buttons, int explodeflag)
  1948.        int     frm_dsdialog(long options, char **buttons, char **strings)
  1949.  
  1950.        ______________________________________________________________________
  1951.  
  1952.        Summary:  Dynamic string dialog.  Builds and conducts a dialog using
  1953.                  the specified strings and buttons.
  1954.  
  1955.        NOTE:     The frm_dsdial() format is outdated; use frm_dsdialog().
  1956.  
  1957.        Input:    The options parameter contains a bitmap of options as
  1958.                  described under Dialog Processing Options.
  1959.  
  1960.                  The buttons parameter is a pointer to an array of string
  1961.                  pointers.  Each element in the array is a pointer to the
  1962.                  string to display in one of the buttons.  You can display up
  1963.                  to 5 buttons.  The end of the array is marked by a NULL
  1964.                  string pointer.  If the buttons parameter is NULL, a single
  1965.                  button labeled "Continue" is displayed.  The buttons are
  1966.                  displayed left-to-right in the same order as  they are in
  1967.                  the array.
  1968.  
  1969.                  The strings parameter is a pointer to an array string
  1970.                  pointers.  Each element in the array is a pointer to a
  1971.                  string displayed within the body of the dialog.  You can
  1972.                  display up to 20 lines of text.  The end of the array is
  1973.  
  1974.        
  1975.        ======================================================================
  1976.        GemFast v1.8                                                   Page 26
  1977.  
  1978.  
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984.  
  1985.                  marked by a NULL string pointer.  If the strings parameter
  1986.                  is NULL, a line containing "<no message>" is displayed in
  1987.                  the body of the dialog.
  1988.  
  1989.        Returns:  The index of the button the user clicked on to exit the
  1990.                  dialog, guaranteed to be in the range of 0 through 4.  The
  1991.                  leftmost button is 0.
  1992.  
  1993.        See Also: frm_defaults() frm_nldialog() frm_printf() frm_qtext()
  1994.  
  1995.        WARNING:  You MUST recompile existing code that calls frm_dsial(). 
  1996.                  Because of 8-character name restrictions, any existing
  1997.                  object/library module will call the new function passing the
  1998.                  parms in the old format if you don't recompile.  Recompiling
  1999.                  will cause the frm_dsdial() macro to put the parms on the
  2000.                  stack in the new order.
  2001.  
  2002.        Details:  This is a fairly hostile function, so let me start by
  2003.                  recommending that you consider using frm_printf() or
  2004.                  frm_qtext() instead of calling this directly.
  2005.  
  2006.                  This function builds a dialog from the text and buttons you
  2007.                  specify, and conducts the dialog with the user.  The dialog
  2008.                  box is automatically sized to contain the widest line of
  2009.                  text in the body, or wide enough to hold all the buttons,
  2010.                  whichever is greater.  It is YOUR responsibility to ensure
  2011.                  that the strings don't result in a width greater than the
  2012.                  current screen width.
  2013.  
  2014.                  Any line of text in the body which has a 0x7F character in
  2015.                  the first position is automatically centered horizontally
  2016.                  (the 0x7F is not displayed).  A 0x7F character in any other
  2017.                  position displays as normal (a little triangle thingy on my
  2018.                  system).
  2019.  
  2020.                  The rightmost button is always the default exit button
  2021.                  unless the FRM_DMUSTSELECT option is specified, in which
  2022.                  case there is no default button.
  2023.  
  2024.  
  2025.  
  2026.  
  2027.  
  2028.  
  2029.  
  2030.  
  2031.  
  2032.  
  2033.  
  2034.  
  2035.  
  2036.  
  2037.  
  2038.  
  2039.  
  2040.        
  2041.        ======================================================================
  2042.        GemFast v1.8                                                   Page 27
  2043.  
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.  
  2051.        Example:  You must create arrays to hold pointers to the button
  2052.                  strings and lines of text in the body.  The following
  2053.                  example displays a dialog with 3 buttons and several lines
  2054.                  of text:
  2055.  
  2056.                      char *buttons[] = {
  2057.                          "Cancel",   /* button 0             */
  2058.                          "Ignore",   /* button 1             */
  2059.                          "Retry",    /* button 2 (default)   */
  2060.                          NULL        /* mark end of array    */
  2061.                      };
  2062.  
  2063.                      char *text[] = {
  2064.                          "\x7F" "Error!",    /* center this line */
  2065.                          "Could not open configuration file.",
  2066.                          " ",
  2067.                          "Please select one of the following options:",
  2068.                          NULL                /* mark end of array    */
  2069.                      };
  2070.  
  2071.                      option = frm_dsdialog(FRM_DSL1TITLE, buttons, text);
  2072.  
  2073.        Source:   aesfuncs\frmdsdia.c
  2074.  
  2075.  
  2076.  
  2077.  
  2078.        int    frm_eflag(OBJECT *ptree, int object, char *fmt, ...)
  2079.        ______________________________________________________________________
  2080.  
  2081.        Summary:  Visually flag a dialog object and display an error message.
  2082.  
  2083.        Input:    The ptree parameter is a pointer to the dialog tree.
  2084.  
  2085.                  The object parameter is the index of the object to be
  2086.                  flagged.
  2087.  
  2088.                  The fmt parameter is a printf-style format string containing
  2089.                  the error message.
  2090.  
  2091.                  The ... parameters are values to substitute into the format
  2092.                  string.
  2093.  
  2094.        Returns:  Zero on success or -1 on failure.
  2095.  
  2096.        See also:
  2097.  
  2098.        Details:  This function reports an error the user made in interacting
  2099.                  with a dialog.  For example, if a dialog contains a editable
  2100.                  field which must contain a value, and the user exits the
  2101.                  dialog without filling in that field, this function is an
  2102.                  ideal way to report the error to the user.
  2103.  
  2104.                  This function works with dialogs already visible on the
  2105.  
  2106.        
  2107.        ======================================================================
  2108.        GemFast v1.8                                                   Page 28
  2109.  
  2110.  
  2111.  
  2112.  
  2113.  
  2114.  
  2115.  
  2116.  
  2117.                  screen.  The object you specify is circled with a red
  2118.                  outline, and a box (a bit like a post-it note) appears
  2119.                  nearby containing the error message text.  When the user
  2120.                  hits a key or clicks the mouse button the screen is restored
  2121.                  to its original appearance and this function returns.
  2122.  
  2123.                  Any type of object can be specified as the object to be
  2124.                  flagged.  For example, if you have a collection of buttons
  2125.                  and the user must select at least one, specify the parent
  2126.                  box which contains the button group.
  2127.  
  2128.                  The error message can contain up to 20 lines of text.  The
  2129.                  longest line must not exceed the screen width.  As a
  2130.                  practical matter, it's a good idea to keep the message down
  2131.                  to 5 or 6 lines, each line no more than about half the
  2132.                  screen width.  Any line that starts with 0x7F is centered in
  2133.                  the display box (the 0x7F character is not displayed).
  2134.  
  2135.                  It is possible for this routine to fail internally, if a VDI
  2136.                  workstation is not available or a blit buffer can't be
  2137.                  allocated.  In this case, an alert appears to tell the user
  2138.                  "An error has occurred with a dialog item you selected or
  2139.                  modified, but there are not enough system resources to
  2140.                  report the exact error."  If this happens, -1 is returned.
  2141.  
  2142.        Example:  To display a dialog, and ensure that the text edit field is
  2143.                  non-blank, the code might look like this:
  2144.  
  2145.                      frm_dialog(FRM_DSTART|FRM_DDRAW, mydialog, 0);
  2146.                      do  {
  2147.                          exitobj = frm_dialog(FRM_DDO, mydialog, EDITFIELD);
  2148.                          if (exitobj == OKAY && edit_field_data[0] == '\0') {
  2149.                              frm_eflag(mydialog, EDITFIELD,
  2150.                                  "\x7F" "You must supply a value between\n"
  2151.                                  "\x7F" " %d and %d for this field",
  2152.                                  lower_range, upper_range);
  2153.                              valid_entry = FALSE;
  2154.                          } else {
  2155.                              valid_entry = TRUE;
  2156.                          }
  2157.                      } while (!valid_entry);
  2158.                      frm_dialog(FRM_DFINISH, mydialog, 0);
  2159.  
  2160.        Source:   aesfuncs\frmeflag.c
  2161.  
  2162.  
  2163.  
  2164.  
  2165.  
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.        
  2173.        ======================================================================
  2174.        GemFast v1.8                                                   Page 29
  2175.  
  2176.  
  2177.  
  2178.  
  2179.  
  2180.  
  2181.  
  2182.  
  2183.        void    frm_enableblit(void)
  2184.        ______________________________________________________________________
  2185.  
  2186.        Summary:  Enable the FRM_USEBLIT and FRM_MOVEABLE dialog options.
  2187.  
  2188.        Input:    Nothing.
  2189.  
  2190.        Returns:  Nothing.
  2191.  
  2192.        See Also: frm_defaults() frm_dialog()
  2193.  
  2194.        Details:  This function sets an internal pointer so that frm_dialog()
  2195.                  can call the grf_blit() function to save and restore the
  2196.                  screen.  You only have to call this function once, then from
  2197.                  that point on the FRM_USEBLIT flag is honored during dialog
  2198.                  processing.
  2199.  
  2200.                  Here's the deal... GemFast needed an option to use blitting
  2201.                  instead of redraw messages to save/restore the screen during
  2202.                  dialog processing.  But, if frm_dialog() were to contain a
  2203.                  direct call to grf_blit(), your linker would pull in all the
  2204.                  VDI code needed to support blitting, even if you didn't want
  2205.                  the FRM_USEBLIT option active in your program.  
  2206.  
  2207.                  So instead of making a direct call to grf_blit(), the
  2208.                  frm_dialog() function checks an internal pointer.  If the
  2209.                  pointer is NULL, blitting is disabled.  If the pointer is
  2210.                  not NULL, and the FRM_USEBLIT flag is set, frm_dialog()
  2211.                  calls the blit function indirectly through the pointer.
  2212.                  Since frm_dialog() has no direct reference to grf_blit(),
  2213.                  the linker won't automatically link in the blit code.
  2214.  
  2215.                  When you call this function, the pointer gets set to point
  2216.                  to the grf_blit() function.  Since that then causes a
  2217.                  reference to grf_blit(), your linker does pull in all the
  2218.                  blit code, but only because you specifically asked it to by
  2219.                  coding a call to this function.
  2220.  
  2221.        Source:   aesfuncs\frmenabl.c
  2222.  
  2223.  
  2224.  
  2225.  
  2226.        int     frm_error(int errcode, char *buttons, char *fmt, ...)
  2227.        ______________________________________________________________________
  2228.  
  2229.        Summary:  Display a formatted message, followed by a standard error
  2230.                  message, in a dialog box.
  2231.  
  2232.        Input:    The errcode parameter is the numeric value of the error to
  2233.                  be reported.
  2234.  
  2235.                  The buttons parameter is a pointer to a string containing
  2236.                  the text of the buttons to display at the bottom of the
  2237.  
  2238.        
  2239.        ======================================================================
  2240.        GemFast v1.8                                                   Page 30
  2241.  
  2242.  
  2243.  
  2244.  
  2245.  
  2246.  
  2247.  
  2248.  
  2249.                  dialog box.  Up to five buttons can be displayed.  A newline
  2250.                  (\n) character terminates each button's text in the string
  2251.                  (you don't need a newline after the last button).  If you
  2252.                  pass a NULL pointer, you get a single button labeled
  2253.                  "Continue".
  2254.  
  2255.                  The fmt parameter is a printf-style format string.
  2256.  
  2257.                  The ... parameters are values to be substituted as specified
  2258.                  in the format string.
  2259.  
  2260.        Returns:  The index of the button the user clicked on to exit the
  2261.                  dialog, guaranteed to be in the range of 0 through 4.  The
  2262.                  leftmost button is 0.
  2263.  
  2264.        See Also: frm_defaults() frm_verror() frm_qerror()
  2265.  
  2266.        Details:  Basically, this is a frm_printf() function that adds an
  2267.                  error message to the end of your formatted message.
  2268.  
  2269.                  This function passes the format string and ... parameters to
  2270.                  sprintf() to create a formatted message.  Then it passes the
  2271.                  errcode parameter to exterror() to get the message
  2272.                  describing that error, and adds it as a separate line below
  2273.                  the lines of your formatted message.  Then it passes the
  2274.                  whole huge text string, along with your buttons pointer, to
  2275.                  frm_nldialog() for display. 
  2276.  
  2277.                  Newline (\n) characters in the result of the sprintf()
  2278.                  formatting delimit the lines as displayed in the dialog. 
  2279.                  Any line that starts with 0x7F is centered in the dialog.
  2280.  
  2281.  
  2282.  
  2283.  
  2284.  
  2285.  
  2286.  
  2287.  
  2288.  
  2289.  
  2290.  
  2291.  
  2292.  
  2293.  
  2294.  
  2295.  
  2296.  
  2297.  
  2298.  
  2299.  
  2300.  
  2301.  
  2302.  
  2303.  
  2304.        
  2305.        ======================================================================
  2306.        GemFast v1.8                                                   Page 31
  2307.  
  2308.  
  2309.  
  2310.  
  2311.  
  2312.  
  2313.  
  2314.  
  2315.                  Your message must be less than 2k long after formatting. 
  2316.                  See the description of frm_printf() for more details.
  2317.  
  2318.        Example:  To report an error in opening a file, you might use:
  2319.  
  2320.                      FILE *thefile;
  2321.  
  2322.                      if (NULL == (thefile = fopen(filename, "r"))) {
  2323.                          return frm_error(errno, "Retry\nCancel", 
  2324.                                      "Can't open file %s",
  2325.                                       filename);
  2326.                      }
  2327.  
  2328.                  If errno was set to -33 (for example) by the fopen()
  2329.                  routine, then this would display a dialog such as:
  2330.  
  2331.                          +--------------------------------+
  2332.                          | Can't open file A:\GEMFAST.DOC | 
  2333.                          | File not found                 |
  2334.                          |                                |
  2335.                          |     | Retry |   | Cancel |     |
  2336.                          +--------------------------------+
  2337.  
  2338.        Source:   aesfuncs\frmerror.c
  2339.  
  2340.  
  2341.  
  2342.  
  2343.        int    frm_menu(long options, OBJECT *ptree, int select_state)
  2344.        ______________________________________________________________________
  2345.  
  2346.        Summary:  Conduct a menu dialog using your object tree.
  2347.  
  2348.        Input:    The options parameter contains a bitmap of options as
  2349.                  described under Dialog Processing Options.
  2350.  
  2351.                  The ptree parameter is a pointer to the dialog tree.
  2352.  
  2353.                  The select_state parameter is the ob_state value the dialog
  2354.                  handler uses to indicate selection of an object.
  2355.  
  2356.        Returns:  The index of the object selected by the user, or NO_OBJECT
  2357.                  if the user didn't select any object.
  2358.  
  2359.        See also: frm_defaults() frm_dsmenu() frm_nlmenu() frm_qmenu()
  2360.  
  2361.  
  2362.  
  2363.  
  2364.  
  2365.  
  2366.  
  2367.  
  2368.  
  2369.  
  2370.        
  2371.        ======================================================================
  2372.        GemFast v1.8                                                   Page 32
  2373.  
  2374.  
  2375.  
  2376.  
  2377.  
  2378.  
  2379.  
  2380.  
  2381.        Details:  This function conducts a menu dialog.  The action of a menu
  2382.                  dialog is similar to that of GEM dropdown menus.  The menu
  2383.                  items are highlighted as the mouse moves through them, so
  2384.                  they are called "hot buttons".  (The items need not be
  2385.                  buttons, any type of object can be used; strings are the
  2386.                  most common hot button object type.)
  2387.  
  2388.                  You can use this function to implement "popup" menus that
  2389.                  can appear anywhere on the screen.  The popup menu looks
  2390.                  like a regular GEM dropdown menu, a box containing strings
  2391.                  that highlight as the mouse moves over them, except that it
  2392.                  can appear anywhere on the screen.  In addition to normal
  2393.                  popup menu dialogs, this function can conduct hybrid dialogs
  2394.                  that contain a mixture of normal exit buttons and menu-type
  2395.                  hot buttons.
  2396.  
  2397.                  For this function to work correctly, your menu dialog tree
  2398.                  has to be constructed with some simple rules in mind. 
  2399.                  Objects with the EXIT, TOUCHEXIT, or DEFAULT flag bits on
  2400.                  will behave as normal.  Objects flagged as SELECTABLE but
  2401.                  without the EXIT, TOUCHEXIT, or DEFAULT bits are the hot
  2402.                  buttons in the dialog; they will highlight as the mouse
  2403.                  crosses them, and a click on them will exit the dialog. The
  2404.                  dialog cannot contain selection (on/off) buttons, radio
  2405.                  buttons, or editable text fields.  Objects with the DISABLED
  2406.                  state bit on will not highlight or cause exit if clicked.
  2407.  
  2408.                  As the mouse passes over enabled hot button objects, they
  2409.                  are visually selected.  The value you pass for select_state
  2410.                  is ORed into the ob_state to visually select an object.  The
  2411.                  most common value should be SELECTED, but in some cases
  2412.                  (especially with colored objects) OUTLINED is a good choice.
  2413.  
  2414.                  If the FRM_DMUSTSELECT option is used, this function will
  2415.                  NOT return NO_OBJECT under any circumstances; only a click
  2416.                  on a hot button or normal exit object will end the dialog. 
  2417.                  Otherwise, if the user clicks on an object which is neither
  2418.                  a normal exit object nor a hot button, this function returns
  2419.                  NO_OBJECT, and if the FRM_MEXITPARENT or FRM_MEXITVICINITY
  2420.                  options are used and the mouse leaves the specified area,
  2421.                  this function returns NO_OBJECT.  
  2422.  
  2423.                  If the mouse button is down on entry to this function, it
  2424.                  waits for the button to be released before doing anything. 
  2425.                  When the user clicks on a TOUCHEXIT object, this function
  2426.                  returns with the mouse button still down, as usual.  When
  2427.                  the user clicks on a hot button object, this function
  2428.                  doesn't return until the user releases the mouse button.  
  2429.  
  2430.                  If the exit object was a normal EXIT or DEFAULT object, it
  2431.                  is deselected as per the rules for frm_dialog().  If the
  2432.                  exit object was a hot button, it remains selected both
  2433.                  visually and in the ob_state field.
  2434.  
  2435.  
  2436.        
  2437.        ======================================================================
  2438.        GemFast v1.8                                                   Page 33
  2439.  
  2440.  
  2441.  
  2442.  
  2443.  
  2444.  
  2445.  
  2446.  
  2447.        Source:   aesfuncs\aplmallo.c
  2448.  
  2449.  
  2450.  
  2451.        int    frm_mkmoveable(OBJECT *ptree, int mover_object)
  2452.        ______________________________________________________________________
  2453.  
  2454.        Summary:  Makes a dialog moveable, and designates the mover object.
  2455.  
  2456.        Input:    The ptree parameter is a pointer to the object tree.
  2457.  
  2458.                  The mover_object parameter is the index of the object in the
  2459.                  tree which will serve as the mover object.
  2460.  
  2461.        Returns:  The object's ob_flags value before it was modified.
  2462.  
  2463.        See Also: frm_dialog()
  2464.  
  2465.        Details:  The frm_dialog() library routine allows users to drag a
  2466.                  dialog box around on the screen.  Use this function to
  2467.                  specify the object within the dialog which serves as the
  2468.                  mover.  
  2469.  
  2470.                  This function changes the ob_flags of the mover object,
  2471.                  turning off some bits and turning on others, as follows:
  2472.  
  2473.                    OFF - SELECTABLE DEFAULT EXIT EDITABLE RBUTTON HIDETREE
  2474.                    ON  - TOUCHEXIT FRM_MOVER
  2475.  
  2476.                  It does not change bits other than those listed.  The
  2477.                  FRM_MOVER bit is defined in GEMFAST.H.
  2478.  
  2479.                  When an object in a dialog tree is defined as the mover
  2480.                  object, that dialog is thereafter considered moveable on
  2481.                  every call to frm_dialog(), even when the FRM_MOVEABLE
  2482.                  option is not used in the call.  The FRM_MOVEABLE dialog
  2483.                  option makes a dialog moveable even when this function
  2484.                  hasn't been called to designate the mover object.  (The root
  2485.                  becomes the mover in that case.)
  2486.  
  2487.                  Use this function if you have designed a specific mover
  2488.                  object into a dialog with your resource editor.  Usually a
  2489.                  mover object is a G_BOXTEXT object, 50%-mask gray filled,
  2490.                  one gl_hbox high, placed across the top of the dialog with a
  2491.                  title string in it.  (IE, it looks like the move bar on a
  2492.                  window.)
  2493.  
  2494.        Source:   aesfuncs\frmmovab.c
  2495.  
  2496.  
  2497.  
  2498.  
  2499.  
  2500.  
  2501.  
  2502.        
  2503.        ======================================================================
  2504.        GemFast v1.8                                                   Page 34
  2505.  
  2506.  
  2507.  
  2508.  
  2509.  
  2510.  
  2511.  
  2512.  
  2513.        int     frm_nldialog(long options, char *buttons, char *strings)
  2514.        ______________________________________________________________________
  2515.  
  2516.        Summary:  Newline-delimited dialog.  Builds and conducts a dialog
  2517.                  using the specified string and buttons.
  2518.  
  2519.        Input:    The options parameter contains a bitmap of options as
  2520.                  described under Dialog Processing Options.
  2521.  
  2522.                  The buttons parameter is a pointer to a string containing
  2523.                  the text of the buttons to display at the bottom of the
  2524.                  dialog box.  Up to five buttons can be displayed.  A newline
  2525.                  (\n) character terminates each button's text in the string
  2526.                  (you don't need a newline after the last button).  If you
  2527.                  pass a NULL pointer, you get a single button labeled
  2528.                  "Continue".
  2529.  
  2530.                  The strings parameter is a pointer to a string containing
  2531.                  the text lines for the body of the dialog.  Up to 20 lines
  2532.                  of text can be displayed.  A newline character terminates
  2533.                  each line's text in the string (you don't need a newline
  2534.                  after the last line).  If you pass a NULL pointer, you get a
  2535.                  single line containing "<no message>".
  2536.  
  2537.        Returns:  The index of the button the user clicked on to exit the
  2538.                  dialog, guaranteed to be in the range of 0 through 4.  The
  2539.                  leftmost button is 0.
  2540.  
  2541.        See Also: frm_defaults() frm_printf() frm_qtext()
  2542.  
  2543.        Details:  This function builds a dialog from the text and buttons you
  2544.                  specify, and conducts the dialog with the user.  The dialog
  2545.                  box is automatically sized to contain the widest line of
  2546.                  text in the body, or wide enough to hold all the buttons,
  2547.                  whichever is greater.  It is YOUR responsibility to ensure
  2548.                  that the strings don't result in a width greater than the
  2549.                  current screen resolution width.
  2550.  
  2551.                  Any line of text in the body which has a 0x7F character in
  2552.                  the first position is automatically centered horizontally
  2553.                  (the 0x7F is not displayed).
  2554.  
  2555.                  You might use this function instead of frm_printf():
  2556.                    - If you don't need to substitute values into the output. 
  2557.                      There is more overhead associated with frm_printf(), in
  2558.                      terms of memory and speed.
  2559.                    - If your message will exceed the 2k limit imposed by
  2560.                      frm_printf().  (Of course, 2k of text is more than will
  2561.                      fit on a standard screen.)
  2562.  
  2563.                  This is a friendlier version of the old frm_dsdialog()
  2564.                  function.  Instead of constructing arrays of pointers to
  2565.                  strings, this allows you to use a single string with newline
  2566.                  characters indicating the line separations.
  2567.  
  2568.        
  2569.        ======================================================================
  2570.        GemFast v1.8                                                   Page 35
  2571.  
  2572.  
  2573.  
  2574.  
  2575.  
  2576.  
  2577.  
  2578.  
  2579.        Example:  The following example displays a dialog containing several
  2580.                  lines of text, and 3 buttons.  This example assumes your
  2581.                  compiler concatenates adjacent string literals into a single
  2582.                  string (ie, "A" "B" is treated as a single string of "AB").
  2583.  
  2584.                      char buttons[] = "Cancel\Nignore\Nretry";
  2585.                      char text[] = 
  2586.                          "\x7F" "Error!\n"
  2587.                          "Cannot open configuration file.\n\n"
  2588.                          "Please select one of these options:\n"
  2589.                          ;
  2590.  
  2591.                      choice = frm_nldialog(FRM_DSL1TITLE, buttons, text);
  2592.  
  2593.        Source:   aesfuncs\frmnldia.c
  2594.  
  2595.  
  2596.  
  2597.  
  2598.        int   frm_nlmenu(long options, char *title, char *selections)
  2599.        ______________________________________________________________________
  2600.  
  2601.        Summary:  Build and conduct a menu dialog using your strings.
  2602.  
  2603.        Input:    The options parameter contains a bitmap of options as
  2604.                  described under Dialog Processing Options.
  2605.  
  2606.                  The title parameter is a pointer to a string which appears
  2607.                  in the menu dialog's title bar.  If a NULL pointer is
  2608.                  passed, the dialog box will have no title bar.
  2609.  
  2610.                  The selections parameter is a pointer to a string containing
  2611.                  the menu's selectable items.  Each selection is delimited by
  2612.                  a newline (\n) character.  (You don't need a newline after
  2613.                  the last selection.)
  2614.  
  2615.        Returns:  The 1-based index of the item selected, or 0 if the last
  2616.                  item was selected, or NO_OBJECT if no item was selected.
  2617.  
  2618.        See also: frm_defaults() frm_qmenu()
  2619.  
  2620.        Details:  This function builds and conducts a "popup" menu dialog.  If
  2621.                  you don't need to specify any options, the frm_qmenu()
  2622.                  function is easier to code.
  2623.  
  2624.                  The title string (if specified) appears centered and
  2625.                  underlined at the top of the dialog box.  The selection
  2626.                  strings appear, one per line, underneath the title.  Any
  2627.                  selection string that starts with 0x7F is centered (the 0x7F
  2628.                  character isn't displayed). Up to 20 selection lines can be
  2629.                  specified.  You must ensure that the title and selection
  2630.                  strings don't exceed the screen width.
  2631.  
  2632.                  The dialog box surrounding the title and strings will always
  2633.  
  2634.        
  2635.        ======================================================================
  2636.        GemFast v1.8                                                   Page 36
  2637.  
  2638.  
  2639.  
  2640.  
  2641.  
  2642.  
  2643.  
  2644.  
  2645.                  have a whitespace gutter of at least one character width on
  2646.                  each side of the widest selection line.  (If the title is
  2647.                  wider than the widest selection, the gutter will be more
  2648.                  than 1 character width).
  2649.  
  2650.                  The return value behavior is a bit complex, but it makes
  2651.                  sense if you follow a basic rule in designing your string
  2652.                  dialogs:  the last item on the menu should always be a Quit,
  2653.                  Cancel, or Exit type selection.  If the user selects the
  2654.                  last item, the return value is 0.  If the user clicks
  2655.                  outside the dialog, the return value is NO_OBJECT (-1). 
  2656.                  Otherwise the return value is the 1-based index of the
  2657.                  selection (first line = 1, second line = 2, etc).
  2658.  
  2659.                  If you specify the FRM_DMUSTSELECT option, the user is
  2660.                  forced to click on a menu selection to exit.  In this case,
  2661.                  the return value is guaranteed not to be NO_OBJECT.
  2662.  
  2663.        Source:   aesfuncs\frmnlmen.c
  2664.  
  2665.  
  2666.  
  2667.        int     frm_printf(long options, char *buttons, char *fmt, ...)
  2668.        ______________________________________________________________________
  2669.  
  2670.        Summary:  Formats a message, builds a dialog box around it, and
  2671.                  conducts the dialog.
  2672.  
  2673.        Input:    The options parameter contains a bitmap of options as
  2674.                  described under Dialog Processing Options.
  2675.  
  2676.                  The buttons parameter is a pointer to a string containing
  2677.                  the text of the buttons to display at the bottom of the
  2678.                  dialog box.  Up to five buttons can be displayed.  A newline
  2679.                  (\n) character terminates each button's text in the string
  2680.                  (you don't need a newline after the last button).  If you
  2681.                  pass a NULL pointer, you get a single button labeled
  2682.                  "Continue".
  2683.  
  2684.                  The fmt parameter is a printf-style format string.
  2685.  
  2686.                  The ... parameters are values to be substituted as specified
  2687.                  in the format string.
  2688.  
  2689.        Returns:  The index of the button the user clicked on to exit the
  2690.                  dialog, guaranteed to be in the range of 0 through 4.  The
  2691.                  leftmost button is 0.
  2692.  
  2693.        See Also: frm_defaults() frm_vprintf() 
  2694.  
  2695.        Details:  This function allocates a 2k buffer to format the string
  2696.                  into.  It passes the specified format string and ...
  2697.                  parameters to sprintf() to create a formatted message.
  2698.                  Newline (\n) characters in the result of the sprintf()
  2699.  
  2700.        
  2701.        ======================================================================
  2702.        GemFast v1.8                                                   Page 37
  2703.  
  2704.  
  2705.  
  2706.  
  2707.  
  2708.  
  2709.  
  2710.  
  2711.                  formatting delimit the lines as displayed in the dialog.
  2712.  
  2713.                  After formatting, it passes the result to frm_nldialog().
  2714.                  The dialog box is automatically sized to contain the widest
  2715.                  line of text in the body, or wide enough to hold all the
  2716.                  buttons, whichever is greater.  It is YOUR responsibility to
  2717.                  ensure that the strings don't result in a width greater than
  2718.                  the current screen resolution width.
  2719.  
  2720.                  Any line of text in the body which has a 0x7F character in
  2721.                  the first position is automatically centered horizontally
  2722.                  (the 0x7F is not displayed).
  2723.  
  2724.                  The 2k buffer allows more than 20 lines of 80 characters. 
  2725.                  This should be longer than any likely message, so no
  2726.                  overflow checking is done.  It is your responsibility not to
  2727.                  pass parameters that would result in more than 2k of
  2728.                  formatted text.
  2729.  
  2730.        Source:   aesfuncs\frmprtf.c
  2731.  
  2732.  
  2733.  
  2734.        int     frm_progress(long options, int increments, 
  2735.                             char *button, char *fmt, ...)
  2736.        ______________________________________________________________________
  2737.  
  2738.        Summary:  Conducts a progress display with a thermometer bar,
  2739.                  formatted text, and an optional abort button.
  2740.  
  2741.        Input:    The options parameter contains a bitmap of options and
  2742.                  actions.  The options are described under Dialog Processing
  2743.                  Options.  In addition, you must OR in exactly one of the
  2744.                  following actions:
  2745.  
  2746.                    FRM_PSTART  - Initialize and draw the dialog.
  2747.                    FRM_PUPDATE - Update the progress display.
  2748.                    FRM_PFINISH - Close and cleanup the dialog.
  2749.  
  2750.                  The increments parameter is interpreted differently,
  2751.                  depending on the action, as described below.
  2752.  
  2753.                  The button parameter is a pointer to a string containing the
  2754.                  text of the abort button in the dialog.  If NULL, the dialog
  2755.                  will not contain an abort button.
  2756.  
  2757.                  The fmt parameter is a printf-style format string.
  2758.  
  2759.                  The ... parameters are values to be substituted as specified
  2760.                  in the format string.
  2761.  
  2762.        Returns:  For FRM_PSTART, 0 on success or a negative error code.  
  2763.                  For FRM_PUPDATE, TRUE (1) if the user clicked on the abort
  2764.                  button, or FALSE (0) if not.
  2765.  
  2766.        
  2767.        ======================================================================
  2768.        GemFast v1.8                                                   Page 38
  2769.  
  2770.  
  2771.  
  2772.  
  2773.  
  2774.  
  2775.  
  2776.  
  2777.                  For FRM_PFINISH, there is no return value.
  2778.  
  2779.        See Also: frm_defaults() frm_vprintf() 
  2780.  
  2781.        Details:  This function dynamically constructs a dialog around your
  2782.                  formatted text, appropriate to keeping the user informed of
  2783.                  the progress of some ongoing task.  The dialog can
  2784.                  optionally contain an abort button if you want the user to
  2785.                  be able to abort the task.  The progress can be indicated by
  2786.                  either or both of two methods:  a graphical thermometer bar
  2787.                  which fills in as progress is made, and a text line in the
  2788.                  body of the dialog that explains the progress with words.
  2789.  
  2790.                  To start the progress dialog, use the FRM_PSTART action
  2791.                  flag.  When you start the dialog, the increments parameter
  2792.                  indicates how many 'ticks' you intend to step the
  2793.                  thermometer bar through.  If this is zero, the dialog will
  2794.                  not have a thermometer bar.  (See the description of
  2795.                  obj_mkthermo() for more details on using a thermometer bar.) 
  2796.                  If you pass a NULL button pointer when you start the dialog,
  2797.                  there won't be an abort button in the dialog, otherwise the
  2798.                  text you specify is used in the button.  The fmt parameter
  2799.                  and values following it are processed as for other formatted
  2800.                  text dialogs.  If you intend to use words as well as the
  2801.                  thermometer bar to indicate progress, the words are
  2802.                  displayed in place of the last line of formatted text in the
  2803.                  body of the dialog.  It doesn't matter if the last line is
  2804.                  initially empty.
  2805.  
  2806.                  To update the progress display, use the FRM_PUPDATE action
  2807.                  flag.  When updating the display, the increments parameter
  2808.                  can have the following values:
  2809.                    
  2810.                    OBJ_TINCREMENT    -   Advance the thermometer bar by one.
  2811.                    Zero              -   Do not change the thermometer bar.
  2812.                    Greater than zero -   Set the thermometer bar increment
  2813.                                          count to the specified number.
  2814.  
  2815.                  The button parameter is ignored for FRM_PUPDATE.  If the fmt
  2816.                  parameter is NULL, no change is made to the text in the
  2817.                  dialog.  If non-NULL, it is a printf-style format string,
  2818.                  and ... arguments may follow it.  In this case, the text is
  2819.                  formatted into a static 128-byte buffer, and is then
  2820.                  displayed in the last line of text in the dialog body
  2821.                  (replacing any existing characters on that line.)  It is
  2822.                  your responsibility to ensure that the new line is less than
  2823.                  128 characters after formatting, and that it is no wider
  2824.                  than the widest line in the existing text.  (IE, the dialog
  2825.                  cannot be made wider once FRM_PSTART has painted it.)  If
  2826.                  the last line of text in the initial dialog was centered,
  2827.                  then all updates will be centered.  (Do NOT specify the 0x7F
  2828.                  centering flag at the start of the update string in fmt.)
  2829.  
  2830.                  To end the dialog and remove it from the screen, use the
  2831.  
  2832.        
  2833.        ======================================================================
  2834.        GemFast v1.8                                                   Page 39
  2835.  
  2836.  
  2837.  
  2838.  
  2839.  
  2840.  
  2841.  
  2842.  
  2843.                  FRM_PFINISH action flag.  All other parameters are ignored.
  2844.  
  2845.                  If you specify an abort button, be sure to check the return
  2846.                  value from every progress display update.
  2847.  
  2848.                  Be aware that if the FRM_MOVEABLE dialog option is in
  2849.                  effect, or if you specify an abort button, a progress update
  2850.                  call can take an indefinite amount of time.  (Because the
  2851.                  user could spend any amount of time dragging the dialog
  2852.                  around or clicking but not releasing the abort exit button.)
  2853.  
  2854.                  You can update both the thermometer and text progress
  2855.                  display on a single call, update just one or the other, or
  2856.                  not update either of them.  You might use the latter to poll
  2857.                  for an abort without changing the display when your
  2858.                  incremental steps take a long time.
  2859.  
  2860.        Example:  Suppose your program formats a floppy disk.  You want to
  2861.                  report the current track and side with words, and update the
  2862.                  thermometer after both sides of each track are done.  You
  2863.                  might use code such as the following:
  2864.  
  2865.                  char trackmsg[] = "Formatting Track: %d Side: %d";
  2866.                  char mainmsg[]  = "Formatting floppy drive %c           \n"
  2867.                                    "\n"      // empty line
  2868.                                    "\x7F "   // track message centered here
  2869.                                    ;
  2870.  
  2871.                  frm_progress(FRM_PSTART, ntracks, NULL, trackmsg, drive);
  2872.                  for (track = 0; track < ntracks; ++track) {
  2873.                      frm_progress(FRM_PUPDATE, 0, NULL, trackmsg, track, 0);
  2874.                      format_it(drive, track, 0);
  2875.                      frm_progress(FRM_PUPDATE, 0, NULL, trackmsg, track, 1);
  2876.                      format_it(drive, track, 1);
  2877.                      frm_progress(FRM_PUPDATE, OBJ_TINCREMENT, NULL, NULL);
  2878.                  }
  2879.                  frm_progress(FRM_PFINISH, 0, NULL, NULL);
  2880.  
  2881.                  Notice that the first line of the main dialog text contains
  2882.                  enough extra spaces to ensure that it will be wider than the
  2883.                  widest possible trackmsg display.  Also notice that the last
  2884.                  line (where the track/side message will appear) has the \x7F
  2885.                  centering flag specified in the original display text, not
  2886.                  in the update text, and also that the \x7F is followed by a
  2887.                  space (since there has to be something besides the \x7F on
  2888.                  the line for it to be noticed as a line).
  2889.  
  2890.        Source:   aesfuncs\frmprogr.c
  2891.  
  2892.  
  2893.  
  2894.  
  2895.  
  2896.  
  2897.  
  2898.        
  2899.        ======================================================================
  2900.        GemFast v1.8                                                   Page 40
  2901.  
  2902.  
  2903.  
  2904.  
  2905.  
  2906.  
  2907.  
  2908.  
  2909.        int    frm_qchoice(char *buttons, char *fmt, ...)
  2910.        ______________________________________________________________________
  2911.  
  2912.        Summary:  Build and conduct dialog with formatted message and up to
  2913.                  five buttons.
  2914.  
  2915.        Input:    The buttons parameter is a pointer to a string containing
  2916.                  the text of the buttons to display at the bottom of the
  2917.                  dialog box.  Up to five buttons can be displayed.  A newline
  2918.                  (\n) character terminates each button's text in the string
  2919.                  (you don't need a newline after the last button).
  2920.  
  2921.                  The fmt parameter is a printf-style format string.
  2922.  
  2923.                  The ... parameters are values to be substituted as specified
  2924.                  in the format string.
  2925.  
  2926.        Returns:  The index of the button the user clicked on to exit the
  2927.                  dialog, guaranteed to be in the range of 0 through 4.  The
  2928.                  leftmost button is 0.
  2929.  
  2930.        See also: frm_defaults() frm_printf() frm_qtext()
  2931.  
  2932.        Details:  This is just a frm_printf() function without an options
  2933.                  parameter.  See the details for frm_printf().
  2934.  
  2935.        Source:   aesfuncs\frmqchoi.c
  2936.  
  2937.  
  2938.  
  2939.  
  2940.        int    frm_qerror(int err, char *fmt, ...)
  2941.        ______________________________________________________________________
  2942.  
  2943.        Summary:  Display formatted error message with Continue button.
  2944.  
  2945.        Input:    The err parameter is the numeric code of the error to be
  2946.                  reported.
  2947.  
  2948.                  The fmt parameter is a printf-style format string.
  2949.  
  2950.                  The ... parameters are values to be substituted as specified
  2951.                  in the format string.
  2952.  
  2953.        Returns:  The same value passed as the err parameter.
  2954.  
  2955.        See also: frm_defaults() frm_error()
  2956.  
  2957.        Details:  This is a frm_error() function with a default exit button
  2958.                  labeled Continue, and a different kind of return value.  See
  2959.                  the details of frm_error() for more information on the error
  2960.                  message lookup and formatting.
  2961.  
  2962.                  The frm_error() function is most appropriate when you are
  2963.  
  2964.        
  2965.        ======================================================================
  2966.        GemFast v1.8                                                   Page 41
  2967.  
  2968.  
  2969.  
  2970.  
  2971.  
  2972.  
  2973.  
  2974.  
  2975.                  presenting the user with multiple options on how to proceed. 
  2976.                  When you are just reporting an error that can't be corrected
  2977.                  or otherwise influenced by the user, frm_qerror() is better,
  2978.                  because it returns the same error code you pass to it.  This
  2979.                  lets you write statements such as:
  2980.  
  2981.                      if (Success != (err = something_that_can_fail())) {
  2982.                          return frm_qerror(err, "Can't do something!");
  2983.                      }
  2984.  
  2985.                  So you can both report the error and return the error status
  2986.                  to the calling routine in a single statement.
  2987.  
  2988.        Source:   aesfuncs\frmqerr.c
  2989.  
  2990.  
  2991.  
  2992.  
  2993.        int    frm_qmenu(char *title, char *selections)
  2994.        ______________________________________________________________________
  2995.  
  2996.        Summary:  Build and conduct a menu dialog using your strings.
  2997.  
  2998.        Input:    The title parameter is a pointer to a string which appears
  2999.                  in the menu dialog's title bar.  If a NULL pointer is
  3000.                  passed, the dialog box will have no title bar.
  3001.  
  3002.                  The selections parameter is a pointer to a string containing
  3003.                  the menu's selectable items.  Each selection is delimited by
  3004.                  a newline (\n) character.  (You don't need a newline after
  3005.                  the last selection.)
  3006.  
  3007.        Returns:  The 1-based index of the item selected, or 0 if the last
  3008.                  item was selected, or NO_OBJECT if no item was selected.
  3009.  
  3010.        See also: frm_defaults() frm_nlmenu()
  3011.  
  3012.        Details:  This is just a frm_nlmenu() function without an options
  3013.                  parameter.  See the details for frm_nlmenu() for a
  3014.                  description of the dialog formatting.  When the default
  3015.                  options are good enough for your popup menu, use this
  3016.                  function.
  3017.  
  3018.        Source:   aesfuncs\frmqmenu.c
  3019.  
  3020.  
  3021.  
  3022.  
  3023.  
  3024.  
  3025.  
  3026.  
  3027.  
  3028.  
  3029.  
  3030.        
  3031.        ======================================================================
  3032.        GemFast v1.8                                                   Page 42
  3033.  
  3034.  
  3035.  
  3036.  
  3037.  
  3038.  
  3039.  
  3040.  
  3041.        void    frm_qtext(char *fmt, ...)
  3042.        ______________________________________________________________________
  3043.  
  3044.        Summary:  Build and conduct dialog with formatted message and Continue
  3045.                  button.
  3046.  
  3047.        Input:    The fmt parameter is a printf-style format string.
  3048.  
  3049.                  The ... parameters are values to be substituted as specified
  3050.                  in the format string.
  3051.  
  3052.        Returns:  Nothing.
  3053.  
  3054.        See also: frm_defaults() frm_printf()
  3055.  
  3056.        Details:  This is just a frm_printf() function without options or
  3057.                  buttons parameters.  See the details for frm_printf().
  3058.  
  3059.                  This function is especially handy for debugging GEM programs
  3060.                  during development, since you can easily insert calls to it:
  3061.  
  3062.                      frm_qtext("At this point, rectangle = %d %d %d %d",
  3063.                          *pcliprect);
  3064.  
  3065.                  But it's also useful whenever you need to communicate with
  3066.                  the user and the default options and a Continue exit button
  3067.                  are good enough.
  3068.  
  3069.        Source:   aesfuncs\frmqtext.c
  3070.  
  3071.  
  3072.  
  3073.  
  3074.        int    frm_question(char *fmt, ...)
  3075.        ______________________________________________________________________
  3076.  
  3077.        Summary:  Build and conduct a formatted dialog with Yes and No exit
  3078.                  buttons.
  3079.  
  3080.        Input:    The fmt parameter is a printf-style format string.
  3081.  
  3082.                  The ... parameters are values to be substituted as specified
  3083.                  in the format string.
  3084.  
  3085.        Returns:  FALSE (0) if the user selected No, or TRUE (1) if the user
  3086.                  selected Yes.
  3087.  
  3088.        See also: frm_defaults()
  3089.  
  3090.  
  3091.  
  3092.  
  3093.  
  3094.  
  3095.  
  3096.        
  3097.        ======================================================================
  3098.        GemFast v1.8                                                   Page 43
  3099.  
  3100.  
  3101.  
  3102.  
  3103.  
  3104.  
  3105.  
  3106.  
  3107.        Details:  This is just a frm_printf() function without an options
  3108.                  parameter, and with two buttons labeled Yes and No.  See the
  3109.                  frm_printf() for details on the message formatting.  The No
  3110.                  button appears on the left, and the Yes button appears on
  3111.                  the right.  Neither button will be a default exit button.
  3112.  
  3113.        Source:   aesfuncs\frmquest.c
  3114.  
  3115.  
  3116.  
  3117.  
  3118.        void    frm_sizes(OBJECT *ptree, GRECT *prect)
  3119.        ______________________________________________________________________
  3120.  
  3121.        Summary:  Calculate the rectangle a dialog will occupy when displayed
  3122.                  on the screen.
  3123.  
  3124.        Input:    The ptree parameter is a pointer to the object tree you want
  3125.                  the sizes of.
  3126.  
  3127.                  The prect parameter is a pointer to a GRECT structure into
  3128.                  which the screen location and sizes are returned.
  3129.  
  3130.        Returns:  Nothing.
  3131.  
  3132.        See Also: obj_clcalc()
  3133.  
  3134.        Details:  This function provides the info you need to conduct the
  3135.                  form_dial() parts of a dialog.  Normally, the form_center()
  3136.                  function is used to center the dialog and obtain the
  3137.                  resulting screen rectangle.  When you want to display a
  3138.                  dialog that isn't centered, use this function instead of
  3139.                  form_center() to obtain the rectangle to pass to
  3140.                  form_dial().
  3141.  
  3142.        NOTE:     This function is implemented as a macro in GEMFAST.H.  The
  3143.                  macro remaps the call to obj_clcalc(), supplying a couple
  3144.                  dummy parms in the process.
  3145.  
  3146.        Source:   aesfuncs\objclcal.c (via macro in GEMFAST.H)
  3147.  
  3148.  
  3149.  
  3150.  
  3151.  
  3152.  
  3153.  
  3154.  
  3155.  
  3156.  
  3157.  
  3158.  
  3159.  
  3160.  
  3161.  
  3162.        
  3163.        ======================================================================
  3164.        GemFast v1.8                                                   Page 44
  3165.  
  3166.  
  3167.  
  3168.  
  3169.  
  3170.  
  3171.  
  3172.  
  3173.        int     frm_verror(int errcode, char **buttons, char *fmt,
  3174.                       va_list args)
  3175.        ______________________________________________________________________
  3176.  
  3177.  
  3178.        NOTE:     This function is identical to frm_error(), except that it
  3179.                  takes a va_list pointer instead of directly accepting the
  3180.                  variable argument list.  If this doesn't mean anything to
  3181.                  you, you probably don't need this function.
  3182.  
  3183.                  See your compiler's runtime library manual, and check out
  3184.                  the difference between your printf() and vprintf()
  3185.                  functions.  That's the same as the difference between
  3186.                  frm_error() and frm_verror().
  3187.  
  3188.        Source:   aesfuncs\frmverro.c
  3189.  
  3190.  
  3191.  
  3192.  
  3193.        int     frm_vprintf(long options, char **buttons, char *fmt,
  3194.                        va_list args)
  3195.        ______________________________________________________________________
  3196.  
  3197.        NOTE:     This function is identical to frm_printf(), except that it
  3198.                  takes a va_list pointer instead of directly accepting the
  3199.                  variable argument list.  If this doesn't mean anything to
  3200.                  you, you probably don't need this function. 
  3201.  
  3202.                  See your compiler's runtime library manual, and check out
  3203.                  the difference between your printf() and vprintf()
  3204.                  functions.  That's the same as the difference between
  3205.                  frm_error() and frm_verror().
  3206.  
  3207.        Source:   aesfuncs\frmvprtf.c
  3208.  
  3209.  
  3210.  
  3211.  
  3212.  
  3213.  
  3214.  
  3215.  
  3216.  
  3217.  
  3218.  
  3219.  
  3220.  
  3221.  
  3222.  
  3223.  
  3224.  
  3225.  
  3226.  
  3227.  
  3228.        
  3229.        ======================================================================
  3230.        GemFast v1.8                                                   Page 45
  3231.  
  3232.  
  3233.  
  3234.  
  3235.  
  3236.  
  3237.  
  3238.  
  3239.        File Selector Library
  3240.  
  3241.  
  3242.                  The file selector library contains functions to conduct file
  3243.                  selector and related dialogs for you.
  3244.  
  3245.  
  3246.  
  3247.  
  3248.        int     fsel_exinput(char *path, char *file, int &exitbutton,
  3249.                             char *prompt)
  3250.        ______________________________________________________________________
  3251.  
  3252.        Summary:  Standard system file selector, with prompting and full
  3253.                  emulation on pre-TOS 1.04 systems.
  3254.  
  3255.        Input:    The inputs are identical to the standard fsel_input()
  3256.                  function, except that an extra parameter, prompt allows you
  3257.                  to provide a prompt string of up to 38 characters.
  3258.  
  3259.        Returns:  TRUE (1) if the user exited via OKAY, or FALSE (0) if the
  3260.                  user exited via CANCEL.
  3261.  
  3262.        See Also:
  3263.  
  3264.        Details:  Atari added the fsel_exinput() prompted file selector
  3265.                  starting with TOS version 1.04.  It allows you to specify a
  3266.                  prompt string to appear in the file selector, and it behaves
  3267.                  slightly differently than the original selector (saves
  3268.                  current default path, etc).
  3269.  
  3270.                  This implementation of fsel_exinput() is compatible with all
  3271.                  TOS versions.  It checks the TOS version, and passes the
  3272.                  call directly to the AES on later versions, or emulates the
  3273.                  new functionality on older AES versions.
  3274.  
  3275.                  While the emulation code increases the size of your
  3276.                  application somewhat, the user-friendliness of the prompted
  3277.                  file selector is a nice feature to have.  I strongly
  3278.                  recommend using this function rather than fsel_input().
  3279.  
  3280.        Source:   aesbind\aesfsel2.s
  3281.  
  3282.  
  3283.  
  3284.  
  3285.        int     fsel_sminput(char *path, char *file, int &exitbutton,
  3286.                             char *prompt)
  3287.        ______________________________________________________________________
  3288.  
  3289.        Summary:  Standard system file selector, with prompting and partial
  3290.                  emulation on pre-TOS 1.04 systems.
  3291.  
  3292.        Input:    The inputs are identical to the standard fsel_input()
  3293.  
  3294.        
  3295.        ======================================================================
  3296.        GemFast v1.8                                                   Page 46
  3297.  
  3298.  
  3299.  
  3300.  
  3301.  
  3302.  
  3303.  
  3304.  
  3305.                  function, except that an extra parameter, prompt allows you
  3306.                  to provide a prompt string of up to 38 characters.
  3307.  
  3308.        Returns:  TRUE (1) if the user exited via OKAY, or FALSE (0) if the
  3309.                  user exited via CANCEL.
  3310.  
  3311.        See Also: fsel_exinput()
  3312.  
  3313.        Details:  This function is similar to fsel_exinput(), except that it
  3314.                  emulates only the prompting feature on older TOS versions;
  3315.                  other behaviors of the new file selector are not emulated. 
  3316.                  This can make your application a bit smaller, and is
  3317.                  appropriate mainly for a desk accessory where a few hundred
  3318.                  bytes of code is significant.
  3319.  
  3320.        Source:   aesbind\aesfsel3.s
  3321.  
  3322.  
  3323.  
  3324.  
  3325.        int     fsl_dialog(long options, char *pfullname, char *ppath,
  3326.                       char *pwild, char *pprompt)
  3327.        ______________________________________________________________________
  3328.  
  3329.        Summary:  Conduct a complete file selector dialog, return the
  3330.                  resulting full device/path/file name.
  3331.  
  3332.        Input:    The options parameter specifies options as a bitmap; OR
  3333.                  together one or more of the following:
  3334.  
  3335.                    FSL_NORMAL     -  A placeholder value, equal to zero.
  3336.                    FSL_FNOPTIONAL -  Selection of a file name is optional.
  3337.                    FSL_PATHONLY   -  Return only the path.
  3338.  
  3339.                  The pfullname parameter points to a buffer into which the
  3340.                  final full device/path/file name is returned.  This pointer
  3341.                  must not be NULL.
  3342.  
  3343.                  The ppath parameter points to a buffer containing the
  3344.                  device/path/wildcard string to display initially in the
  3345.                  dialog.  The final device/path/wildcard ends up in this
  3346.                  buffer after the call. If a NULL pointer is passed, a
  3347.                  default buffer internal to the function is used.
  3348.  
  3349.                  The pwild parameter, if non-NULL, points to a wildcard mask
  3350.                  string to be forced onto the end of the ppath string before
  3351.                  displaying the dialog. 
  3352.  
  3353.                  The pprompt parameter points to the prompt string to display
  3354.                  in the file selector.  If a NULL pointer is passed, a
  3355.                  default prompt ("Select File") is used.
  3356.  
  3357.  
  3358.        Returns:  TRUE (1) if the user exited via OKAY and the input passed
  3359.  
  3360.        
  3361.        ======================================================================
  3362.        GemFast v1.8                                                   Page 47
  3363.  
  3364.  
  3365.  
  3366.  
  3367.  
  3368.  
  3369.  
  3370.  
  3371.                  the validations specified in the options.  FALSE (0) if the
  3372.                  user exited via CANCEL, or any validation failed.  If this
  3373.                  function returns FALSE, the buffers pointed to by pfullname
  3374.                  and ppath are not modified.
  3375.  
  3376.        See Also:
  3377.  
  3378.        Details:  This function simplifies file selector interaction with the
  3379.                  user.  It is somewhat complex, because it attempts to
  3380.                  include all the functionality a complex program would need. 
  3381.                  But most of the complexity is covered with simple defaults,
  3382.                  and the function is pretty easy to use.
  3383.  
  3384.                  If you specify the FSL_FNOPTIONAL flag, this function does
  3385.                  not ensure the presence of a filename in the selection made
  3386.                  by the user; the return value indicates only whether the
  3387.                  user clicked on OKAY or CANCEL.  (Normally, this function
  3388.                  returns zero if no filename was selected; ie, a missing
  3389.                  filename is treated as a CANCEL.)
  3390.  
  3391.                  If you specify the FSL_PATHONLY flag, not only is the
  3392.                  filename entry optional, this function removes any filename
  3393.                  and returns just the path part.  The path is guaranteed to
  3394.                  have a trailing '\' character.
  3395.  
  3396.                  I recommend that you use 128-character buffers to hold
  3397.                  pathnames.  This function does no checking of pathname
  3398.                  lengths or truncation of long names, but 128 characters is
  3399.                  the accepted standard for GEMDOS programming.
  3400.  
  3401.                  About the ppath string:  If this pointer is NULL, a 128-byte
  3402.                  static internal buffer is used instead.  If the string is
  3403.                  empty, this function automatically initializes it to the
  3404.                  current device and path.  If the string is not empty, is
  3405.                  MUST have either a wildcard string on the end of it, or a
  3406.                  trailing '\' character.  (If it contains a path without a
  3407.                  wildcard or trailing '\', the last node of the pathname is
  3408.                  assumed to be a wildcard, and the user will get real
  3409.                  confused.)  If it has a trailing '\', a default wildcard of
  3410.                  "*.*" is added.
  3411.  
  3412.                  About the pwild string:  After processing the ppath string
  3413.                  as described above, the pwild pointer is checked.  If it is
  3414.                  non-NULL, then the wildcard on the end of the ppath string
  3415.                  is replaced with the pwild string.
  3416.  
  3417.                  Once the ppath and pwild strings are processed,
  3418.                  fsel_exinput() is invoked.  If the user selects CANCEL, this
  3419.                  function returns FALSE immediately.  If the user selects
  3420.                  OKAY, the presence of a filename is verified (unless the
  3421.                  options say the filename is optional).  If the filename
  3422.                  validation passes, the path and wildcard shown in the file
  3423.                  selector are copied to the ppath buffer.  Then the full
  3424.                  device/path/filename string is assembled into your pfullname
  3425.  
  3426.        
  3427.        ======================================================================
  3428.        GemFast v1.8                                                   Page 48
  3429.  
  3430.  
  3431.  
  3432.  
  3433.  
  3434.  
  3435.  
  3436.  
  3437.                  buffer, and TRUE is returned.
  3438.  
  3439.                  Now we come to the religious part of this description: 
  3440.                  usage recommendations.  I hate the way folks use file
  3441.                  selectors in programs, and I want to establish one
  3442.                  overriding rule:  the user should always see the same path
  3443.                  s/he saw last time in the file selector.  That can be
  3444.                  modified a bit in some situations, as you'll see...
  3445.  
  3446.                  For a simple program that only deals with one type of file,
  3447.                  I recommend that you use a NULL ppath and pwild pointer, and
  3448.                  let this function do all the work.  The first time you call
  3449.                  this function, it self-initializes to the current path. 
  3450.                  After that, the user will always see the same thing s/he
  3451.                  last saw.  If you want to be just a little trickier, pass an
  3452.                  appropriate pwild pointer the first time you call this
  3453.                  function, so that the user starts out seeing the right kind
  3454.                  of files.  Then pass a NULL pwild pointer on subsequent
  3455.                  calls, so that if the user decided to look at a different
  3456.                  type of file, it stays that way.
  3457.  
  3458.                  Sometimes a program only deals with a certain kind of file. 
  3459.                  Perhaps it can only read .RSC files, and only write .XYZ
  3460.                  files.  In this case, use a NULL ppath pointer, but non-NULL
  3461.                  pwild pointers in your calls.  If the user wants to try
  3462.                  something other than a .RSC file, it won't be prevented, but
  3463.                  will be strongly discouraged.  However, don't do this sort
  3464.                  of thing if you expect to read .TXT files.  Maybe the user
  3465.                  has renamed all the .TXT files to .DOC, and it's not your
  3466.                  job to discourage that by facistly forcing the wildcard on
  3467.                  every call.
  3468.  
  3469.                  For a complex program that deals with several types of
  3470.                  files, it can make sense to maintain several current paths. 
  3471.                  Perhaps you store graphics images in one subdirectory, sound
  3472.                  bites in another, and script files in a third place.  If the
  3473.                  user does a Load Image, then later does a Load Script, it
  3474.                  doesn't make sense to have the script file selector open up
  3475.                  to the image path just because that's what the user last
  3476.                  saw.  It would make more sense to open the selector up to
  3477.                  the path the user saw last time s/he did something with
  3478.                  script files.  For this situation, use a non-NULL ppath
  3479.                  pointer.  You can have several path buffers in your program
  3480.                  (script_path, image_path, etc).  Then just pass the same
  3481.                  path buffer every time you want to select that type of file,
  3482.                  and the user will always see the right path for that
  3483.                  filetype.
  3484.  
  3485.                  When you maintain several path buffers for different types
  3486.                  of files, you can start out with all the path buffers empty. 
  3487.                  The first time you pass the empty buffer to this function,
  3488.                  it'll get initialized to the current device and path.  Or,
  3489.                  you can pre-initialize the buffers yourself during program
  3490.                  startup (perhaps loading them from a config file).  If you
  3491.  
  3492.        
  3493.        ======================================================================
  3494.        GemFast v1.8                                                   Page 49
  3495.  
  3496.  
  3497.  
  3498.  
  3499.  
  3500.  
  3501.  
  3502.  
  3503.                  initialize them yourself, remember to ensure that they end
  3504.                  in a wildcard mask or have a trailing '\' character.
  3505.  
  3506.                  The thing to avoid at all costs is using a non-NULL ppath
  3507.                  pointer and explicitly reloading a path into that buffer
  3508.                  before each call to this function.  I've used programs that
  3509.                  explicitly loaded A:\*.* into the path before each call to
  3510.                  the file selector.  But I never used any of them for very
  3511.                  long; they've all ended up in the trash.
  3512.  
  3513.                  [End of sermon]
  3514.  
  3515.        Source:   aesfuncs\fsldialo.c
  3516.  
  3517.  
  3518.  
  3519.  
  3520.  
  3521.  
  3522.  
  3523.  
  3524.  
  3525.  
  3526.  
  3527.  
  3528.  
  3529.  
  3530.  
  3531.  
  3532.  
  3533.  
  3534.  
  3535.  
  3536.  
  3537.  
  3538.  
  3539.  
  3540.  
  3541.  
  3542.  
  3543.  
  3544.  
  3545.  
  3546.  
  3547.  
  3548.  
  3549.  
  3550.  
  3551.  
  3552.  
  3553.  
  3554.  
  3555.  
  3556.  
  3557.  
  3558.        
  3559.        ======================================================================
  3560.        GemFast v1.8                                                   Page 50
  3561.  
  3562.  
  3563.  
  3564.  
  3565.  
  3566.  
  3567.  
  3568.  
  3569.        Graphics Library
  3570.  
  3571.  
  3572.                  The graphics library contains functions to help you deal
  3573.                  with the graphics screen and the mouse.  It includes
  3574.                  functions to get and set the current mouse shape, and
  3575.                  functions to easily blit areas of the screen from and to
  3576.                  memory buffers.
  3577.  
  3578.  
  3579.  
  3580.  
  3581.        void    gra_qmstate(int *px, int *py, int *pb)
  3582.        ______________________________________________________________________
  3583.  
  3584.        NOTE:     This old function is being phased out.  It used Line-A to
  3585.                  get the mouse state, and Atari has announced the death of
  3586.                  Line-A.  Use the standard graf_mkstate() function.
  3587.  
  3588.                  Your existing code will not break, but the new support for
  3589.                  this function just calls graf_mkstate(), so you might as
  3590.                  well convert your code.
  3591.  
  3592.        Source:   aesxbind\gramouse.c
  3593.  
  3594.  
  3595.  
  3596.  
  3597.        void    gra_qofmouse(void)
  3598.        ______________________________________________________________________
  3599.  
  3600.        NOTE:     This old function is being phased out.  It used Line-A to
  3601.                  hide the mouse, and Atari has announced the death of Line-A. 
  3602.                  Use the standard graf_mouse() function.
  3603.  
  3604.                  Your existing code will not break, but the new support for
  3605.                  this function just calls graf_mouse(), so you might as well
  3606.                  convert your code.
  3607.  
  3608.        Source:   aesxbind\gramouse.c
  3609.  
  3610.  
  3611.  
  3612.  
  3613.  
  3614.  
  3615.  
  3616.  
  3617.  
  3618.  
  3619.  
  3620.  
  3621.  
  3622.  
  3623.  
  3624.        
  3625.        ======================================================================
  3626.        GemFast v1.8                                                   Page 51
  3627.  
  3628.  
  3629.  
  3630.  
  3631.  
  3632.  
  3633.  
  3634.  
  3635.        void    gra_qonmouse(void)
  3636.        ______________________________________________________________________
  3637.  
  3638.        NOTE:     This old function is being phased out.  It used Line-A to
  3639.                  show the mouse, and Atari has announced the death of Line-A. 
  3640.                  Use the standard graf_mouse() function.
  3641.  
  3642.                  Your existing code will not break, but the new support for
  3643.                  this function just calls graf_mouse(), so you might as well
  3644.                  convert your code.
  3645.  
  3646.        Source:   aesxbind\gramouse.c
  3647.  
  3648.  
  3649.  
  3650.  
  3651.        long    grf_blit(int options, void *pbuffer, void *prect)
  3652.        ______________________________________________________________________
  3653.  
  3654.        Summary:  Blits a rectangle between the screen and a memory buffer.
  3655.  
  3656.        Input:    The options parameter specifies options as a bitmap.  One of
  3657.                  the following must be specified:
  3658.         
  3659.                    GRF_BFROMSCREEN - Blit from screen to memory.
  3660.                    GRF_BTOSCREEN   - Blit from memory to screen.
  3661.                    GRF_BMEMCALC    - Do not blit, just calculate and return
  3662.                                      the amount of memory required.
  3663.  
  3664.                  In addition, the following may be ORed in with the above:
  3665.  
  3666.                    GRF_BOBJTREE    - The prect parameter is a pointer to an
  3667.                                      object tree, instead of a GRECT.
  3668.  
  3669.                  The pbuffer parameter is a pointer to the memory buffer for
  3670.                  the blit.  If the GRF_BMEMCALC flag is specified, this may
  3671.                  be NULL, otherwise it must not be NULL.
  3672.  
  3673.                  The prect parameter is normally a pointer to a GRECT that
  3674.                  describes the screen area to blit.  If the GRF_BOBJTREE flag
  3675.                  is specified, it is a pointer to an object tree, and the
  3676.                  rectangle the dialog occupies on-screen is used.
  3677.  
  3678.        Returns:  The amount of memory needed to do the blit.  If this value
  3679.                  is zero, no portion of the blit intersects the physical
  3680.                  screen.  (IE, the blit is completely clipped.)
  3681.  
  3682.        See Also: grf_memblit()
  3683.  
  3684.        Details:  This function simplifies the process of using blits to save
  3685.                  and restore portions of the screen.
  3686.  
  3687.                  If you specify the GRF_BOBJTREE flag, the prect pointer is
  3688.                  interpreted as a pointer to an object tree instead of a
  3689.  
  3690.        
  3691.        ======================================================================
  3692.        GemFast v1.8                                                   Page 52
  3693.  
  3694.  
  3695.  
  3696.  
  3697.  
  3698.  
  3699.  
  3700.  
  3701.                  pointer to a GRECT.  In this case, the screen rectangle is
  3702.                  obtained using frm_sizes(prect,...), so that the object
  3703.                  tree's screen location is the blit area.
  3704.  
  3705.                  If you specify the GRF_BMEMCALC flag, this function
  3706.                  calculates and returns the size needed for a memory buffer
  3707.                  to do this blit, but it does not actually blit anything.  
  3708.  
  3709.                  This function copies the prect rectangle to a work area and
  3710.                  does an rc_intersect(&gl_rfscrn, &workrect) to clip the blit
  3711.                  to the physical screen.  (VDI tends to hang the machine if
  3712.                  you try to do off-screen blits.)  If no portion of the
  3713.                  rectangle is on-screen, no blit is done, and zero is
  3714.                  returned.  Your prect rectangle can have negative x/y
  3715.                  values, but it must not have negative width or height.
  3716.  
  3717.                  The memory buffer is assumed to be the right size for the
  3718.                  blit.  The blit origin in the buffer is always 0,0.  In
  3719.                  other words, you can't allocate a single buffer and store
  3720.                  several discontiguous pieces of the screen into it, you must
  3721.                  allocate a separate buffer for each piece of the screen you
  3722.                  want to save simultaneously.  It is your responsibility to
  3723.                  use a buffer that is big enough to hold the contents of the
  3724.                  specified screen rectangle.  (Using a buffer bigger than
  3725.                  necessary doesn't hurt.)
  3726.  
  3727.                  This function uses the VDI shared workstation.  The mouse is
  3728.                  automatically hidden during the blit.
  3729.  
  3730.        Source:   aesfuncs\grfblit.c
  3731.  
  3732.  
  3733.  
  3734.  
  3735.  
  3736.        void *   grf_memblit(int options, void *pbuffer, void *prect)
  3737.        ______________________________________________________________________
  3738.  
  3739.        Summary:  Allocates a buffer and blits a screen area into it, or
  3740.                  restores the screen and frees the buffer.
  3741.  
  3742.        Input:    The options parameter specifies options as a bitmap.  Only
  3743.                  one option is currently available:
  3744.  
  3745.                    GRF_BOBJTREE    - The prect parameter is a pointer to an
  3746.                                      object tree, instead of a GRECT.
  3747.  
  3748.                  The pbuffer parameter both indicates blit direction and
  3749.                  specifies the buffer to use on a restore.
  3750.  
  3751.                  The prect parameter is a normally pointer to a GRECT that
  3752.                  describes the screen area to blit.  If the GRF_BOBJTREE flag
  3753.                  is specified, it is a pointer to an object tree, and the
  3754.                  rectangle the dialog occupies on-screen is used.
  3755.  
  3756.        
  3757.        ======================================================================
  3758.        GemFast v1.8                                                   Page 53
  3759.  
  3760.  
  3761.  
  3762.  
  3763.  
  3764.  
  3765.  
  3766.  
  3767.        Returns:  A pointer to the allocated buffer.  A NULL return value
  3768.                  indicates that a buffer could not be allocated, or the blit
  3769.                  area did not intersect the physical screen.
  3770.  
  3771.        See Also: grf_blit()
  3772.  
  3773.        Details:  This function provides the easiest way to save and restore
  3774.                  an area of the screen.
  3775.  
  3776.                  When you pass a NULL buffer pointer, this function allocates
  3777.                  a buffer (of just the right size), and saves the specified
  3778.                  screen rectangle into it.  It returns a pointer to the
  3779.                  allocated buffer.
  3780.  
  3781.                  To restore that screen area, call this function again,
  3782.                  passing the pointer it returned to you when you saved the
  3783.                  screen area.  It restores the screen and deallocates the
  3784.                  buffer.  (The return value in this case is garbage.)
  3785.  
  3786.                  When saving a screen area, be sure to check the returned
  3787.                  pointer to ensure the blit worked.
  3788.  
  3789.                  Any number of screen areas can be saved simultaneously with
  3790.                  multiple calls to this function, since the buffers are
  3791.                  dynamically allocated.
  3792.  
  3793.                  The mouse is automatically hidden during the blit.
  3794.  
  3795.        Source:   aesfuncs\grfmblit.c
  3796.  
  3797.  
  3798.  
  3799.  
  3800.        int     graf_mouse(int shape, void *pform)
  3801.        int     grf_mouse(int shape, void *pform)
  3802.        ______________________________________________________________________
  3803.  
  3804.        Summary:  Inquire, alter, or restore the mouse cursor shape.
  3805.  
  3806.        NOTE:     A macro in GEMFAST.H remaps graf_mouse to grf_mouse so that
  3807.                  your existing code need not be changed.
  3808.  
  3809.        Input:    The shape parameter specifies the action of this function. 
  3810.                  It can have any of the standard GEM-defined values (ARROW,
  3811.                  BUSYBEE, M_ON, etc).  In addition, there is one special
  3812.                  action available:
  3813.  
  3814.                    GRF_MSINQUIRE -   Return information about the current
  3815.                                      mouse shape; do not change the mouse.
  3816.  
  3817.                  The pform parameter is interpreted differently depending on
  3818.                  the value of the shape parameter; details below.
  3819.  
  3820.        Returns:  The shape the cursor was set to before the call, or 0 if an
  3821.  
  3822.        
  3823.        ======================================================================
  3824.        GemFast v1.8                                                   Page 54
  3825.  
  3826.  
  3827.  
  3828.  
  3829.  
  3830.  
  3831.  
  3832.  
  3833.                  error occurred.  When the prior shape was ARROW, it is
  3834.                  handled specially; details below.
  3835.  
  3836.        See Also:
  3837.  
  3838.        Details:  GEM doesn't provide a way to inquire what the current mouse
  3839.                  shape is, so this function does it for you.  It keeps track
  3840.                  of the current mouse shape in static variables so that it
  3841.                  can return the value to you.  Naturally, this only works if
  3842.                  all changes to the mouse shape are made through this
  3843.                  routine, so a macro in GEMFAST.H remaps your existing
  3844.                  graf_mouse() calls through this function.
  3845.  
  3846.                  The GEM graf_mouse() function returns zero/non-zero, and
  3847.                  this function is compatible with that.  But, when this
  3848.                  function returns a non-zero value (indicating success), that
  3849.                  value is the shape of the mouse before call.  You can use
  3850.                  this to temporarily change the mouse shape then restore it:
  3851.  
  3852.                      old_shape = graf_mouse(ARROW, NULL);
  3853.                      /* do something */
  3854.                      graf_mouse(old_shape, NULL);
  3855.  
  3856.                  If the old shape was ARROW (0), this function can't return
  3857.                  ARROW, because that would look like a failure of the call. 
  3858.                  Instead, it returns the special value 200, defined as
  3859.                  GRF_MSALTARROW.  When you pass GRF_MSALTARROW as the shape
  3860.                  parameter to this function, it is automatically translated
  3861.                  back to ARROW before being passed along to GEM in the real
  3862.                  graf_mouse() call.
  3863.  
  3864.                  If you pass the special value GRF_MSINQUIRE as the shape
  3865.                  parameter to this function, it returns information about the
  3866.                  current mouse shape without changing it.  In this case, the
  3867.                  pform parameter is interpreted differently.  If pform is
  3868.                  NULL, this function just returns the current shape number
  3869.                  without changing the shape.  If you pass a non-NULL pform
  3870.                  with GRF_MSINQUIRE, it is a pointer to a pointer variable
  3871.                  into which the current user-defined form pointer is stored. 
  3872.                  This feature is used as follows:
  3873.          
  3874.                      void *oldform;
  3875.                      int  oldshape;
  3876.  
  3877.                      oldshape = graf_mouse(GRF_MSINQUIRE, &oldform);
  3878.                      graf_mouse(USER_DEF, myform);
  3879.                      /* do something with your custom mouse form */
  3880.                      graf_mouse(oldshape, oldform);
  3881.  
  3882.                  You only need to use this technique if you are going to
  3883.                  change the shape to your own user-defined shape.  If the
  3884.                  mouse was a user-defined shape, and you change it to a
  3885.  
  3886.  
  3887.  
  3888.        
  3889.        ======================================================================
  3890.        GemFast v1.8                                                   Page 55
  3891.  
  3892.  
  3893.  
  3894.  
  3895.  
  3896.  
  3897.  
  3898.  
  3899.                  standard system shape, then graf_mouse(oldshape, NULL) will
  3900.                  restore the prior user-defined shape properly.
  3901.  
  3902.        Source:   aesfuncs\grfmouse.c
  3903.  
  3904.  
  3905.  
  3906.  
  3907.  
  3908.  
  3909.  
  3910.  
  3911.  
  3912.  
  3913.  
  3914.  
  3915.  
  3916.  
  3917.  
  3918.  
  3919.  
  3920.  
  3921.  
  3922.  
  3923.  
  3924.  
  3925.  
  3926.  
  3927.  
  3928.  
  3929.  
  3930.  
  3931.  
  3932.  
  3933.  
  3934.  
  3935.  
  3936.  
  3937.  
  3938.  
  3939.  
  3940.  
  3941.  
  3942.  
  3943.  
  3944.  
  3945.  
  3946.  
  3947.  
  3948.  
  3949.  
  3950.  
  3951.  
  3952.  
  3953.  
  3954.        
  3955.        ======================================================================
  3956.        GemFast v1.8                                                   Page 56
  3957.  
  3958.  
  3959.  
  3960.  
  3961.  
  3962.  
  3963.  
  3964.  
  3965.        Menu Library
  3966.  
  3967.  
  3968.                  The menu library contains functions which help you manage
  3969.                  the GEM menu bar.  It contains several functions that exist
  3970.                  primarily to support GemFast internals, and several things
  3971.                  which provide functionality GEM doesn't give you directly.
  3972.  
  3973.  
  3974.  
  3975.  
  3976.  
  3977.        int     menu_bar(OBJECT *ptree, int on_off_flag)
  3978.        int     mnu_bar(OBJECT *ptree, int on_off_flag, long reserved)
  3979.        ______________________________________________________________________
  3980.  
  3981.        Summary:  Turn the menu bar on or off in a way that it can
  3982.                  transparently enabled and disabled.
  3983.  
  3984.        NOTE:     A macro in GEMFAST.H remaps menu_bar to mnu_bar so that your
  3985.                  existing code need not be changed.
  3986.  
  3987.        Input:    The ptree parameter is a pointer to the object tree
  3988.                  describing the menu.
  3989.  
  3990.                  The on_off_flag parameter indicates whether you are turning
  3991.                  the specified menu on (ie, installing it), or turning it off
  3992.                  (removing it).
  3993.  
  3994.                  The reserved parameter is for future use, and must be zero. 
  3995.                  (The menu_bar() macro supplies the zero.)
  3996.  
  3997.        Returns:  Zero for failure or non-zero for success.
  3998.  
  3999.        See Also: mnu_enable() mnu_disable()
  4000.  
  4001.        Details:  This function helps implement menus that can be temporarily
  4002.                  disabled.  There are times when a library routine wants to
  4003.                  disable menu processing without disabling window controls as
  4004.                  well (in other words, wind_update() is sometimes too
  4005.                  strong).  GEM's menu_bar(whatever,0) function can disable
  4006.                  the menu, but then you have to have the pointer to the menu
  4007.                  tree available to re-enable it.
  4008.  
  4009.                  This function simply remembers the menu tree pointer when
  4010.                  the application turns on its menu.  This allows the related
  4011.                  mnu_enable() and mnu_disable() functions to make menu_bar()
  4012.                  calls to turn the menu on and off using whatever menu tree
  4013.                  was last supplied by the application.
  4014.  
  4015.                  This works because menu_bar(whatever, 0) disables menu
  4016.                  processing, but does not actually erase the menu from the
  4017.  
  4018.  
  4019.  
  4020.        
  4021.        ======================================================================
  4022.        GemFast v1.8                                                   Page 57
  4023.  
  4024.  
  4025.  
  4026.  
  4027.  
  4028.  
  4029.  
  4030.  
  4031.                  screen.  If GEM's menu_bar() ever starts erasing the menu
  4032.                  visually, I'm going to have a lot of kludging to do.
  4033.  
  4034.        Source:   aesfuncs\mnubar.c
  4035.  
  4036.  
  4037.  
  4038.  
  4039.        void    mnu_disable(void)
  4040.        ______________________________________________________________________
  4041.  
  4042.        Summary:  Disable the menu bar from responding to the mouse.
  4043.  
  4044.        Input:    Nothing.
  4045.  
  4046.        Returns:  Nothing.
  4047.  
  4048.        See Also: mnu_enable() mnu_bar()
  4049.  
  4050.        Details:  This function prevents the menu bar from responding to the
  4051.                  mouse, but it does not also disable window controls like
  4052.                  wind_update() does.  It works like hide/show mouse calls, in
  4053.                  that 3 calls to mnu_disable() will require 3 calls to
  4054.                  mnu_enable() to get the menus active again.
  4055.  
  4056.        Source:   aesfuncs\mnubar.c
  4057.  
  4058.  
  4059.  
  4060.  
  4061.        void    mnu_enable(void)
  4062.        ______________________________________________________________________
  4063.  
  4064.        Summary:  Re-enable the menu bar to respond to the mouse.
  4065.  
  4066.        Input:    Nothing.
  4067.  
  4068.        Returns:  Nothing.
  4069.  
  4070.        See Also: mnu_disable() mnu_bar()
  4071.  
  4072.        Details:  This function allows the menu bar to begin responding to
  4073.                  mouse events again after it had been disabled.  It works
  4074.                  like hide/show mouse calls, in that 3 calls to mnu_disable()
  4075.                  will require 3 calls to mnu_enable() to get the menus active
  4076.                  again.
  4077.  
  4078.        Source:   aesfuncs\mnubar.c
  4079.  
  4080.  
  4081.  
  4082.  
  4083.  
  4084.  
  4085.  
  4086.        
  4087.        ======================================================================
  4088.        GemFast v1.8                                                   Page 58
  4089.  
  4090.  
  4091.  
  4092.  
  4093.  
  4094.  
  4095.  
  4096.  
  4097.        void    mnu_erase(void)
  4098.        ______________________________________________________________________
  4099.  
  4100.        Summary:  Turn of the menu bar and remove it from the screen.
  4101.  
  4102.        Input:    Nothing.
  4103.  
  4104.        Returns:  Nothing.
  4105.  
  4106.        See Also: mnu_tbar()
  4107.  
  4108.        Details:  This function turns off the current menu (if any), and
  4109.                  erases the menu bar area of the screen.
  4110.  
  4111.        Source:   aesfuncs\mnutbar.c
  4112.  
  4113.  
  4114.  
  4115.  
  4116.        void    mnu_tbar(char *title)
  4117.        ______________________________________________________________________
  4118.  
  4119.        Summary:  Turn of the menu bar and display a text string in its place.
  4120.  
  4121.        Input:    The title parameter is a pointer to the string to be
  4122.                  displayed in the menu bar.
  4123.  
  4124.        Returns:  Nothing.
  4125.  
  4126.        See Also: mnu_erase()
  4127.  
  4128.        Details:  This function turns off the current menu (if any), and
  4129.                  displays the specified string centered in the menu bar area
  4130.                  of the screen.  
  4131.  
  4132.        Example:  If your program allows the user to "shell out" to other
  4133.                  programs, you can use this function to display the name of
  4134.                  the program before executing it, like the GEM desktop does:
  4135.  
  4136.                  void exec_a_program(char *fname)
  4137.                  {
  4138.                      static char fullpath[128];
  4139.                      strcpy(fullpath, fname);
  4140.                      if (!shel_find(fullpath)) 
  4141.                          return frm_qerror(-33, "Can't exec program");
  4142.                      graf_mouse(BEE, NULL);      // make mouse a BEE, and put
  4143.                      mnu_tbar(fullpath);         // program name in menu bar.
  4144.                      Pexec(0, fullpath, "\0", NULL);
  4145.                      menu_bar(my_normal_menu,1); // restore our menu bar, and
  4146.                      graf_mouse(ARROW, NULL);    // make sure mouse is ARROW.
  4147.                      return Success;
  4148.                  }
  4149.  
  4150.        Source:   aesfuncs\mnutbar.c
  4151.  
  4152.        
  4153.        ======================================================================
  4154.        GemFast v1.8                                                   Page 59
  4155.  
  4156.  
  4157.  
  4158.  
  4159.  
  4160.  
  4161.  
  4162.  
  4163.  
  4164.  
  4165.  
  4166.  
  4167.  
  4168.  
  4169.  
  4170.  
  4171.  
  4172.  
  4173.  
  4174.  
  4175.  
  4176.  
  4177.  
  4178.  
  4179.  
  4180.  
  4181.  
  4182.  
  4183.  
  4184.  
  4185.  
  4186.  
  4187.  
  4188.  
  4189.  
  4190.  
  4191.  
  4192.  
  4193.  
  4194.  
  4195.  
  4196.  
  4197.  
  4198.  
  4199.  
  4200.  
  4201.  
  4202.  
  4203.  
  4204.  
  4205.  
  4206.  
  4207.  
  4208.  
  4209.  
  4210.  
  4211.  
  4212.  
  4213.  
  4214.  
  4215.  
  4216.  
  4217.  
  4218.        
  4219.        ======================================================================
  4220.        GemFast v1.8                                                   Page 60
  4221.  
  4222.  
  4223.  
  4224.  
  4225.  
  4226.  
  4227.  
  4228.  
  4229.        Object Library
  4230.  
  4231.  
  4232.                  The object library contains functions which manipulate an
  4233.                  object in a tree.  There are functions for getting and
  4234.                  setting most of the common object structure fields.
  4235.  
  4236.                  In general, object library functions affect just one object
  4237.                  in a tree, or in some cases all the objects which are
  4238.                  children of one object.  Resource library functions affect a
  4239.                  whole tree or a list of unrelated objects in a tree. 
  4240.  
  4241.  
  4242.  
  4243.  
  4244.  
  4245.        int    obj_bmbuttons(OBJECT *ptree, int parent, int select_state,
  4246.                             int newbits)
  4247.        ______________________________________________________________________
  4248.  
  4249.        Summary:  Translate a group of buttons with extended type info into a
  4250.                  bitmap-vector or vice versa.
  4251.  
  4252.        Input:    The ptree parameter is a pointer to the tree containing the
  4253.                  button group.
  4254.  
  4255.                  The parent parameter is the index of the object which is the
  4256.                  direct parent of the group of buttons.
  4257.  
  4258.                  The select_state parameter is a mask of ob_state bits used
  4259.                  to select an object.
  4260.  
  4261.                  The newbits parameter contains the bitmap to be translated
  4262.                  into selected buttons, or it contains the special value
  4263.                  OBJ_BMINQUIRE which indicates that you want to get the
  4264.                  bitmap describing the selected buttons without changing the
  4265.                  button states.
  4266.  
  4267.        Returns:  A bitmap of the buttons that were selected before the call.
  4268.  
  4269.        See also: rsc_sxtypes() obj_xtfind()
  4270.  
  4271.        Details:  This function is useful when you have a group of buttons in
  4272.                  a dialog which represent on/off options that your program
  4273.                  can handle.  When your program supports a variety of
  4274.                  options, a common technique is to use bits within a word to
  4275.                  represent the options.  (Like the options in the GemFast
  4276.                  forms library.)  This function helps you translate the state
  4277.                  of the dialog buttons to and from the bitmapped
  4278.                  representation used within your program.
  4279.  
  4280.                  The extended object type field is the upper 8 bits of the
  4281.                  ob_type field in an object.  These bits are always available
  4282.                  to your program for any use you want.  By setting the
  4283.  
  4284.        
  4285.        ======================================================================
  4286.        GemFast v1.8                                                   Page 61
  4287.  
  4288.  
  4289.  
  4290.  
  4291.  
  4292.  
  4293.  
  4294.  
  4295.                  extended object types for a collection of buttons to the
  4296.                  values representing your bitmapped options, you can easily
  4297.                  relate each button to the option it represents within your
  4298.                  program.  Up to 8 options can be encoded in a group of
  4299.                  buttons in this way.  If you need more than 8 options, just
  4300.                  use more than one parent object, and put 8 buttons in each
  4301.                  parent.  (The parent can be an IBOX so that the user doesn't
  4302.                  know you've performed any arbitrary grouping.)  Some
  4303.                  resource editors let you specify the extended object type
  4304.                  when you define your dialog.  If yours doesn't, just use the
  4305.                  rsc_sxtypes() function during program startup.
  4306.  
  4307.                  When you pass a newbits value of OBJ_BMINQUIRE, this
  4308.                  function checks each object within the parent.  It ANDs each
  4309.                  object's ob_state field with the select_state parameter, and
  4310.                  if the result is non-zero, it ORs the object's extended
  4311.                  object type into the return value.  The return value is the
  4312.                  bitmap of all extended type values for objects that were in
  4313.                  a selected state.
  4314.  
  4315.                  When you pass any value other than OBJ_BMINQUIRE for the
  4316.                  newbits parameter, this function changes the state of the
  4317.                  objects as well as returning the old-state bitmap.  In this
  4318.                  case, it again checks each object within the parent, but it
  4319.                  ANDs the newbits with the extended object type of each
  4320.                  object.  When the result is non-zero, it ORs the
  4321.                  select_state value into the object's ob_state; when the
  4322.                  result is zero, it ANDs ~select_state with the object's
  4323.                  ob_state.  This results in selecting all buttons which
  4324.                  represent 1 bits in the newbits parameter, and deselecting
  4325.                  all buttons which represent 0 bits in newbits.
  4326.  
  4327.                  Note that the objects don't have to be buttons; this
  4328.                  function keys off of the extended object type and state
  4329.                  fields only.
  4330.  
  4331.        Example:  Suppose your program has four options, and a dialog box that
  4332.                  lets users turn each of those options on or off with
  4333.                  selection (ie, non-radio) buttons.  The following code
  4334.  
  4335.  
  4336.  
  4337.  
  4338.  
  4339.  
  4340.  
  4341.  
  4342.  
  4343.  
  4344.  
  4345.  
  4346.  
  4347.  
  4348.  
  4349.  
  4350.        
  4351.        ======================================================================
  4352.        GemFast v1.8                                                   Page 62
  4353.  
  4354.  
  4355.  
  4356.  
  4357.  
  4358.  
  4359.  
  4360.  
  4361.                  fragments illustrate how this function helps:
  4362.  
  4363.                      #define AUTOSAVE    0x0001
  4364.                      #define AUTOBACKUP  0x0002
  4365.                      #define FILEOUTPUT  0x0004
  4366.                      #define PRINTOUTPUT 0x0008
  4367.  
  4368.                      int options = AUTOSAVE | FILEOUTPUT; // initial defaults
  4369.  
  4370.                      OBJECT *option_dialog;
  4371.  
  4372.                      void prog_init()
  4373.                      {
  4374.                          appl_init();
  4375.                          rsrc_load(etc, etc);
  4376.                          rsc_gtrees(OPTIONDIALOG, &option_dialog, -1);
  4377.  
  4378.                          /*
  4379.                           * set button extended types to our bit values...
  4380.                           */
  4381.  
  4382.                          rsc_sxtypes(option_dialog,
  4383.                              AUTOSAVE_BUTTON, AUTOSAVE,
  4384.                              AUTOBACK_BUTTON, AUTOBACKUP,
  4385.                              FILEOUT_BUTTON,  FILEOUTPUT,
  4386.                              PRTOUT_BUTTON,   PRINTFOUTPUT,
  4387.                              -1);
  4388.                      }
  4389.  
  4390.                      void do_options_dialog()
  4391.                      {
  4392.                          /*
  4393.                           * translate current options to selected buttons...
  4394.                           */
  4395.  
  4396.                          obj_bmbuttons(option_dialog, 
  4397.                              BUTTON_PARENT, SELECTED, options);
  4398.  
  4399.                          /* 
  4400.                           * do dialog...
  4401.                           */
  4402.  
  4403.                          frm_dialog(FRM_CENTER, option_dialog, 0);
  4404.  
  4405.                          /*
  4406.                           * translate buttons now selected back into options
  4407.                           * variable...
  4408.                           */
  4409.  
  4410.                          options = obj_bmbuttons(option_dialog,
  4411.                              BUTTON_PARENT, SELECTED, OBJ_BMINQUIRE);
  4412.                      }
  4413.  
  4414.        Source:   aesfuncs\objbmbtn.c
  4415.  
  4416.        
  4417.        ======================================================================
  4418.        GemFast v1.8                                                   Page 63
  4419.  
  4420.  
  4421.  
  4422.  
  4423.  
  4424.  
  4425.  
  4426.  
  4427.  
  4428.  
  4429.        int    obj_clcalc(OBJECT *ptree, int object, GRECT *pgrect,
  4430.                           VRECT *pvrect)
  4431.        ______________________________________________________________________
  4432.  
  4433.        Summary:  Calculates a clipping rectangle for an object.
  4434.  
  4435.        Input:    The ptree parameter is a pointer to the tree containing the
  4436.                  object.
  4437.  
  4438.                  The object parameter is the index of the object to be
  4439.                  calculated.
  4440.  
  4441.                  The pgrect parameter is a pointer to a GRECT structure into
  4442.                  which the results are returned.  If this is NULL, the
  4443.                  results are not returned in GRECT format.
  4444.  
  4445.                  The pvrect parameter is a pointer to a VRECT structure into
  4446.                  which the results are returned.  If this is NULL, the
  4447.                  results are not returned in VRECT format.
  4448.  
  4449.        Returns:  The adjustment applied to the object's basic rectangle to
  4450.                  arrive at the on-screen rectangle.  Always zero or greater. 
  4451.                  (EG, a value of 4 indicates that the returned rectangle is 4
  4452.                  pixels larger on all sides than the rectangle described by
  4453.                  the object's xywh values.)
  4454.  
  4455.        See Also: frm_sizes()
  4456.  
  4457.        Details:  This function calculates the rectangle that an object
  4458.                  occupies on the screen.  It understands that some objects
  4459.                  have an on-screen size larger than their xywh values imply. 
  4460.                  (IE, when the object is OUTLINED, SHADOWED, etc).
  4461.  
  4462.                  If you want to calculate the rectangle for an entire tree,
  4463.                  the frm_sizes() function is easier to code.
  4464.  
  4465.                  Do not count on this function for absolute precision.  The
  4466.                  calculated rectangle will fully enclose the object, but it
  4467.                  might be a pixel or two larger than the visual boundary of
  4468.                  the object.  (This is because of the arcane rules for
  4469.                  SHADOWED objects in particular.)  So this function will
  4470.                  always work if you want to save the screen under the object;
  4471.                  you may just save a couple pixels more than you need to. 
  4472.                  But, it may not be sufficient if you want to accurately
  4473.                  outline the object with a box drawn via VDI calls, for
  4474.                  example.
  4475.  
  4476.                  Prior GemFast docs stated that this function was obsolete
  4477.  
  4478.  
  4479.  
  4480.  
  4481.  
  4482.        
  4483.        ======================================================================
  4484.        GemFast v1.8                                                   Page 64
  4485.  
  4486.  
  4487.  
  4488.  
  4489.  
  4490.  
  4491.  
  4492.  
  4493.                  and was being phased out.  Instead of obsoleting it, I threw
  4494.                  away the buggy old assembler code and rewrote it in C.  I
  4495.                  don't plan to phase it out anymore.
  4496.  
  4497.        Source:   aesfuncs\objclcal.c
  4498.  
  4499.  
  4500.  
  4501.  
  4502.        void    obj_flchange(OBJECT *ptree, int object, int newflags,
  4503.                         int drawflag [ ,GRECT *cliprect ])
  4504.        ______________________________________________________________________
  4505.  
  4506.        Summary:  Change an object's flags, with optional redraw.
  4507.  
  4508.        Input:    The ptree parameter is a pointer to the tree containing the
  4509.                  object to change.
  4510.  
  4511.                  The object parameter is the index of the object to change.
  4512.  
  4513.                  The newflags parameter specifies which object flag bits to
  4514.                  change; details below.  
  4515.  
  4516.                  The drawflag parameter specifies whether the object is to be
  4517.                  visually updated on the screen, use one of the following:
  4518.  
  4519.                    OBJ_NODRAW   (0) -    Don't update the screen.
  4520.                    OBJ_WITHDRAW (1) -    Update the screen.
  4521.                    OBJ_CLIPDRAW (2) -    Update the screen with clipping.
  4522.  
  4523.                  The cliprect parameter is an optional pointer to a rectangle
  4524.                  which will be used to clip the redraw of the object.  This
  4525.                  parameter is only used when the drawflag parameter is equal
  4526.                  to OBJ_CLIPDRAW.
  4527.  
  4528.        Returns:  Nothing.
  4529.  
  4530.        See Also:
  4531.  
  4532.        Details:  This function provides a simple way to change the object
  4533.                  flag bits for any object.
  4534.  
  4535.                  If the high bit of the newflags parameter is set, an AND is
  4536.                  used to mask off bits in the object flags.  If the high bit
  4537.                  is not set, an OR is used to set bits in the object flags. 
  4538.                  This allows a newflags value of DEFAULT to set the default
  4539.                  bit, and a value of ~DEFAULT to unset it.
  4540.  
  4541.                  When the drawflag parameter is non-zero, an objc_draw() call
  4542.                  is automatically done after the flags are changed.  The
  4543.                  objc_draw() is always done starting at the root object and
  4544.                  drawing to MAX_DEPTH, and the draw is clipped to the on-
  4545.                  screen rectangle of the object being changed.  This allows a
  4546.                  change that sets HIDETREE to properly hide the object
  4547.  
  4548.        
  4549.        ======================================================================
  4550.        GemFast v1.8                                                   Page 65
  4551.  
  4552.  
  4553.  
  4554.  
  4555.  
  4556.  
  4557.  
  4558.  
  4559.                  visually, because the parent of the object is redrawn, but
  4560.                  the object itself is not.
  4561.  
  4562.                  When your dialog is in a window or another situation in
  4563.                  which you might need to clip the redraw, use the
  4564.                  OBJ_CLIPDRAW option, and provide a pointer to the clipping
  4565.                  rectangle.  If the draw option is not CLIPDRAW, the clip
  4566.                  pointer need not be specified.
  4567.  
  4568.        Source:   aesfuncs\objflchg.c
  4569.  
  4570.  
  4571.  
  4572.  
  4573.        int      obj_mkthermo(OBJECT *ptree, int object, int increments)
  4574.        ______________________________________________________________________
  4575.  
  4576.        Summary:  Transforms a G_BOX object into a G_THERMO progress display
  4577.                  object.
  4578.  
  4579.        Input:    The ptree parameter is a pointer to the object tree
  4580.                  containing the object to be transformed.
  4581.         
  4582.                  The object parameter is the index of the G_BOX object to be
  4583.                  transformed.
  4584.  
  4585.                  The increments parameter is the number of increments or
  4586.                  'ticks' the thermometer will display.
  4587.  
  4588.        Returns:  Zero on success, or a negative error code.
  4589.  
  4590.        See Also: obj_udthermo() frm_progress()
  4591.  
  4592.        Details:  This function implements a new type of object that can be
  4593.                  contained in a standard object tree, the G_THERMO object. 
  4594.                  The object is used to indicate progress by incrementally
  4595.                  filling more of the object interior as progress is made. 
  4596.                  Use the obj_udthermo() to increment the filled portion of
  4597.                  the object and optionally update the object on-screen.
  4598.  
  4599.                  To use a G_THERMO object, design your object tree as usual,
  4600.                  placing a G_BOX object at the location and sizes you want
  4601.                  the G_THERMO object to appear.  At runtime, call this
  4602.                  function to transform the G_BOX into a G_THERMO.  The fill
  4603.                  pattern in your original G_BOX object is used as the fill
  4604.                  pattern for the G_THERMO.  You cannot change the fill
  4605.                  pattern once the object is transformed.
  4606.  
  4607.                  The interior of the object is always filled from left to
  4608.                  right as progress increments are made.  There is no way to
  4609.                  implement vertical or right to left progress at this time.
  4610.  
  4611.                  The increments parameter indicates how many increments the
  4612.                  thermo bar is capable of.  Based on the increments, the
  4613.  
  4614.        
  4615.        ======================================================================
  4616.        GemFast v1.8                                                   Page 66
  4617.  
  4618.  
  4619.  
  4620.  
  4621.  
  4622.  
  4623.  
  4624.  
  4625.                  G_THERMO object is sized in the horizontal dimension and
  4626.                  centered it within its original horizontal location.  The
  4627.                  resizing ensures that the total width is a multiple of the
  4628.                  number of increments that you requested.  For example, if
  4629.                  your original G_BOX was 210 pixels wide, and you request 100
  4630.                  increments in the G_THERMO, then the G_THERMO will be 200
  4631.                  pixels wide, and each time you increment the progress
  4632.                  display, it will add 2 pixels of shading to the interior. 
  4633.                  Because the actual object is 10 pixels smaller than the
  4634.                  original box, it is displayed at an X offset 5 pixels to the
  4635.                  right of the original object.
  4636.  
  4637.                  Do not specify more increments than the width of the
  4638.                  original G_BOX object; it would result in an increment width
  4639.                  of zero pixels per tick.  If you do so, this function
  4640.                  returns -64 (range error), and doesn't transform the object.
  4641.  
  4642.                  You can call this function more than once.  On the second
  4643.                  and subsequent calls, it detects that the transformation has
  4644.                  been done already, and it just recalculates the G_THERMO's
  4645.                  width and placement based on the new increments, and zeros
  4646.                  out the current increment count.  If the dialog containing
  4647.                  the G_THERMO is visible on-screen, this does not update the
  4648.                  on-screen object; use objc_draw() to redraw.
  4649.          
  4650.                  This function changes the original G_BOX object into a
  4651.                  G_USERDEF object, then attaches an XUSERBLK structure to the
  4652.                  ob_spec of the object.  Once you have transformed an object
  4653.                  into a G_THERMO, you MUST NOT modify the ob_spec field.  A
  4654.                  G_THERMO object is like a normal object in all respects,
  4655.                  except that it does NOT respond to the values in ob_state
  4656.                  when it is drawn.  That is, there is no SELECTED, OUTLINED,
  4657.                  or other state that is visually different from the normal
  4658.                  state.  It does respond normally to all ob_flags values.
  4659.  
  4660.                  Because it is, to GEM, a single object, normal operations
  4661.                  like objc_draw() work on a G_THERMO object just fine.  (IE,
  4662.                  you don't need to call obj_udthermo() to draw the object
  4663.                  unless you also want to change the increment count.)  If you
  4664.                  have a dialog containing a G_THERMO in a window, then your
  4665.                  objc_draw() calls to repaint the window will automatically
  4666.                  repaint the G_THERMO object(s) using their current increment
  4667.                  count.
  4668.  
  4669.                  See the obj_udthermo() function for an example of using
  4670.                  obj_mkthermo().
  4671.  
  4672.        Note:     Poking around in the source code, you'll find that there's a
  4673.                  ThermoInfo structure attached to G_THERMO objects through
  4674.                  the ob_spec field.  Do NOT access this data directly, use
  4675.                  only the obj_mkthermo() and obj_udthermo() functions to
  4676.                  access the object.  The details of the ThermoInfo structure
  4677.                  are quite likely to change in the next version.
  4678.  
  4679.  
  4680.        
  4681.        ======================================================================
  4682.        GemFast v1.8                                                   Page 67
  4683.  
  4684.  
  4685.  
  4686.  
  4687.  
  4688.  
  4689.  
  4690.  
  4691.        Source:   aesfuncs\objtherm.c
  4692.  
  4693.  
  4694.  
  4695.  
  4696.        void    obj_mxuserdef(XUSERBLK *pblk, OBJECT *pobj, void *pcode)
  4697.        ______________________________________________________________________
  4698.  
  4699.        Summary:  Transforms a system-defined object into a GemFast-defined
  4700.                  extended G_USERDEF object.
  4701.  
  4702.        Input:    The pblk parameter is a pointer to an XUSERBLK structure
  4703.                  that will be attached to the object by this function.
  4704.  
  4705.                  The pobj parameter is a pointer to the object to be
  4706.                  transformed.
  4707.  
  4708.                  The pcode parameter is a pointer to the function which
  4709.                  renders the object during objc_draw() processing.
  4710.  
  4711.        Returns:  Nothing.
  4712.  
  4713.        See Also:
  4714.  
  4715.        Details:  Say what?  This function exists primarily to support other
  4716.                  internal library functions.  If you don't know what a
  4717.                  G_USERDEF object is, you probably don't need this.  If you
  4718.                  want to know, read on.  The data structures and types
  4719.                  discussed below are all defined in GEMFAST.H.
  4720.  
  4721.                  If you think up a new type of graphics object (perhaps a
  4722.                  full-color icon), or you want to change the appearance of a
  4723.                  standard object, GEM provides the G_USERDEF object type to
  4724.                  help you out.  With a G_USERDEF object, the ob_spec field is
  4725.                  a pointer to a USERBLK structure.  The USERBLK contains a
  4726.                  pointer to a function that draws the object, and a 4-byte
  4727.                  field containing application-specific info.  When the AES is
  4728.                  processing an objc_draw() call, it calls your drawing
  4729.                  function for any G_USERDEF objects it finds.
  4730.  
  4731.                  If you want to transform a standard object into a G_USERDEF
  4732.                  object so that you can draw it differently, you have to
  4733.                  change the ob_type field and ob_spec field in the original
  4734.                  object -- six bytes of information.  But the USERBLK
  4735.                  structure gives you only four bytes to store application-
  4736.                  specific info, so you can't preserve both the original
  4737.                  ob_type and ob_spec in the USERBLK.
  4738.  
  4739.                  An XUSERBLK structure provides additional space for you to
  4740.                  store things in.  The first field is still a pointer to the
  4741.                  drawing routine, for GEM compatibility.  The second field
  4742.                  (where application data goes in a regular USERBLK) is a
  4743.                  pointer to the XUSERBLK itself.  Following this are an
  4744.                  ob_type and ob_spec field for preserving the info from the
  4745.  
  4746.        
  4747.        ======================================================================
  4748.        GemFast v1.8                                                   Page 68
  4749.  
  4750.  
  4751.  
  4752.  
  4753.  
  4754.  
  4755.  
  4756.  
  4757.                  original object.  Following that are two more fields for
  4758.                  storing up to six more bytes of your own application-
  4759.                  specific info.
  4760.  
  4761.                  To transform an object, allocate an XUSERBLK structure, and
  4762.                  call this function, passing pointers to the XUSERBLK, the
  4763.                  original object, and your custom drawing routine.  This
  4764.                  function copies the original object's ob_type and ob_spec
  4765.                  into the XUSERBLK. It then changes the original object's
  4766.                  ob_type and ob_spec, making it a G_USERDEF object.  It also
  4767.                  sets up the ub_code and ub_self fields of the XUSERBLK.  If
  4768.                  you want to store some of your own data in the XUSERBLK's
  4769.                  userflags or userdata fields, you can do so either before or
  4770.                  after calling this function; this function doesn't touch
  4771.                  those fields in the XUSERBLK.
  4772.  
  4773.                  If the original object has a non-zero value in the extended
  4774.                  object type (upper byte of ob_type), this function preserves
  4775.                  that info in the original object, and does not copy that
  4776.                  part of the ob_type to the XUSERBLK.
  4777.  
  4778.                  Other GemFast functions understand extended G_USERDEF
  4779.                  objects set up by this function.  For example, if you have a
  4780.                  button object, and you transform it into an extended
  4781.                  G_USERDEF so that it gets drawn differently, the pointer to
  4782.                  the button string is moved from the original ob_spec field
  4783.                  to the XUSERBLK structure.  But, the rsc_sstrings() and
  4784.                  rsc_gstrings() functions will still get or set the string
  4785.                  pointer correctly.  (IE, they'll work with the pointer in
  4786.                  the XUSERBLK rather than incorrectly disturbing the object's
  4787.                  ob_spec pointer.)
  4788.  
  4789.                  If you are writing a routine that needs to cope with
  4790.                  G_USERDEF objects blindly, you can determine whether the
  4791.                  object has a USERBLK or XUSERBLK attached to it by examining
  4792.                  the second field of the attachment.  In an XUSERBLK, the
  4793.                  second field (ub_self) always points to the head of the
  4794.                  structure; this uniquely identifies the attachment as an
  4795.                  XUSERBLK.
  4796.  
  4797.                  Details on how to code a custom drawing routine are beyond
  4798.                  the scope of this discussion.  But, for some hints, see the
  4799.                  source code for the GemFast rsc_rrbuttons() and
  4800.                  rsc_cubuttons() functions.
  4801.  
  4802.                  Note added 12/06/92: The parameters for calling this
  4803.                  function WILL change in the next release, if you use it, try
  4804.                  to isolate all your calls to one easy-to-find location.
  4805.  
  4806.        Source:   aesfuncs\objmxud.c
  4807.  
  4808.  
  4809.  
  4810.  
  4811.  
  4812.        
  4813.        ======================================================================
  4814.        GemFast v1.8                                                   Page 69
  4815.  
  4816.  
  4817.  
  4818.  
  4819.  
  4820.  
  4821.  
  4822.  
  4823.        void    obj_offxywh(OBJECT *ptree, int object, GRECT *prect)
  4824.        ______________________________________________________________________
  4825.  
  4826.        Summary:  Get the screen-adjusted xywh values for an object.
  4827.  
  4828.        Input:    The ptree parameter is a pointer to the object tree.
  4829.  
  4830.                  The object parameter is the index of the object.
  4831.  
  4832.                  The prect parameter is a pointer to the rectangle into which
  4833.                  the object's xywh values are returned.
  4834.  
  4835.        Returns:  Nothing.
  4836.  
  4837.        See Also: obj_clcalc()
  4838.  
  4839.        Details:  This function gets the screen-adjusted xywh values for the
  4840.                  object.  It does NOT take into account that some objects are
  4841.                  visually larger than their xywh values imply (ie, OUTLINED
  4842.                  objects).  Use the obj_clcalc() function if you need to
  4843.                  account for the actual visual area an object occupies on the
  4844.                  screen.
  4845.  
  4846.        Source:   aesfuncs\objoxywh.c
  4847.  
  4848.  
  4849.  
  4850.  
  4851.        int     obj_parent(OBJECT *ptree, int object)
  4852.        ______________________________________________________________________
  4853.  
  4854.        Summary:  Return the parent object for the specified object.
  4855.  
  4856.        Input:    The ptree parameter is a pointer to the object tree.
  4857.  
  4858.                  The object parameter is the index of the object.
  4859.  
  4860.        Returns:  The index of the parent object.
  4861.  
  4862.        See Also:
  4863.  
  4864.        Details:  By definition, the root object has no parent.  If you try to
  4865.                  get the parent of the root, zero is returned, as if the root
  4866.                  were its own parent.
  4867.  
  4868.        Source:   aesfuncs\objrbutl.c
  4869.  
  4870.  
  4871.  
  4872.  
  4873.  
  4874.  
  4875.  
  4876.  
  4877.  
  4878.        
  4879.        ======================================================================
  4880.        GemFast v1.8                                                   Page 70
  4881.  
  4882.  
  4883.  
  4884.  
  4885.  
  4886.  
  4887.  
  4888.  
  4889.        char ** obj_ppstring(OBJECT *pobj)
  4890.        ______________________________________________________________________
  4891.  
  4892.        Summary:  Return a pointer to an object's string pointer.
  4893.  
  4894.        Input:    The pobj parameter is a pointer to the object.
  4895.  
  4896.        Returns:  A pointer to the object's string pointer.  Undefined if the
  4897.                  object isn't string-related.
  4898.  
  4899.        See Also: rsc_gstrings() rsc_sstrings()
  4900.  
  4901.        Details:  This routine exists primarily to support other library
  4902.                  routines, but you can use it directly.  It returns a pointer
  4903.                  to the string pointer for a string-related object.  String-
  4904.                  related objects and the pointers this finds for each are:
  4905.  
  4906.                      G_STRING    The ob_spec string pointer.
  4907.                      G_BUTTON    The ob_spec button-text pointer.
  4908.                      G_TITLE     The ob_spec title-text pointer.
  4909.                      G_TEXT      The te_ptext pointer.
  4910.                      G_FTEXT     The te_ptext pointer.
  4911.                      G_BOXTEXT   The te_ptext pointer.
  4912.                      G_FBOXTEXT  The te_ptext pointer.
  4913.                      G_ICON      The ib_ptext pointer.
  4914.  
  4915.                  This function understands how to find the real string
  4916.                  pointer for each of these object types.  It copes with the
  4917.                  INDIRECT flag.  It understands extended G_USERDEF objects,
  4918.                  where ob_spec has been moved into the XUSERBLK.
  4919.  
  4920.                  If you're not used to working with double-indirect pointers,
  4921.                  I recommend that you consider using the rsc_sstrings() and
  4922.                  rsc_grstrings() functions.
  4923.  
  4924.        Source:   aesfuncs\objppstr.c
  4925.  
  4926.  
  4927.  
  4928.  
  4929.        int     obj_rbfind(OBJECT *ptree, int parent, int rbstate)
  4930.        ______________________________________________________________________
  4931.  
  4932.        Summary:  Finds the selected button in a group of radio buttons.
  4933.  
  4934.        Input:    The ptree parameter is a pointer to the object tree.
  4935.  
  4936.                  The parent parameter is the index of the parent which
  4937.                  contains the radio buttons.
  4938.  
  4939.                  The rbstate parameter is the ob_state mask to look for.
  4940.  
  4941.        Returns:  The index of the selected object, or NO_OBJECT (-1) if no
  4942.                  radio buttons are in the desired state.
  4943.  
  4944.        
  4945.        ======================================================================
  4946.        GemFast v1.8                                                   Page 71
  4947.  
  4948.  
  4949.  
  4950.  
  4951.  
  4952.  
  4953.  
  4954.  
  4955.        See Also: obj_rbselect()
  4956.  
  4957.        Details:  This function walks through the children of the specified
  4958.                  parent.  For each child object with the RBUTTON bit set in
  4959.                  the ob_flags, it does an AND of the child's ob_state against
  4960.                  the rbstate parameter.  It returns the index of the first
  4961.                  child object which has a non-zero result from the AND.  It
  4962.                  returns NO_OBJECT if the result was zero for all children.
  4963.  
  4964.                  The most common use of this function is to pass SELECTED for
  4965.                  the rbstate parameter.  Sometimes it's handy to use OUTLINED
  4966.                  or another state to indicate selection of an object, so this
  4967.                  function allows any state bit(s) to be specified.  If you
  4968.                  pass a combination of bits, (ie, (SELECTED|OUTLINED)), then
  4969.                  this function finds the first radio button with either (not
  4970.                  both) of those bits set.
  4971.  
  4972.        Source:   aesfuncs\objrbutl.c
  4973.  
  4974.  
  4975.  
  4976.  
  4977.        int     obj_rbselect(OBJECT *ptree, int selobj, int selstate)
  4978.        ______________________________________________________________________
  4979.  
  4980.        Summary:  De-selects current radio button, selects a new one.
  4981.  
  4982.        Input:    The ptree parameter is a pointer to the object tree.
  4983.  
  4984.                  The selobj parameter is the index of the new radio button to
  4985.                  be selected.
  4986.  
  4987.                  The selstate parameter specifies the ob_state bits which are
  4988.                  turned off in the current radio button and turned on in the
  4989.                  new one.
  4990.  
  4991.        Returns:  The index of the radio button that was selected before the
  4992.                  call, or NO_OBJECT if no buttons were previously selected.
  4993.  
  4994.        See Also: obj_rbfind()
  4995.  
  4996.        Details:  This function is the easiest way to set a given radio button
  4997.                  to a selected state.  If a button in the group is already
  4998.                  selected, this function de-selects it before selecting the
  4999.                  new button.
  5000.  
  5001.                  Note that this function does NOT update the buttons on-
  5002.                  screen, it only changes the ob_state words.  Use this for
  5003.                  setting up a dialog before displaying it.  After that, the
  5004.                  GEM forms manager updates the ob_state and the on-screen
  5005.                  object during dialog processing.
  5006.  
  5007.        Source:   aesfuncs\objrbutl.c
  5008.  
  5009.  
  5010.        
  5011.        ======================================================================
  5012.        GemFast v1.8                                                   Page 72
  5013.  
  5014.  
  5015.  
  5016.  
  5017.  
  5018.  
  5019.  
  5020.  
  5021.  
  5022.  
  5023.        void    obj_stchange(OBJECT *ptree, int object, int newstate,
  5024.                         int drawflag [, GRECT *cliprect ])
  5025.        ______________________________________________________________________
  5026.  
  5027.        Summary:  Change an object's state, with optional redraw.
  5028.  
  5029.        Input:    The ptree parameter is a pointer to the tree containing the
  5030.                  object to change.
  5031.  
  5032.                  The object parameter is the index of the object to change.
  5033.  
  5034.                  The newstate parameter specifies which object state bits to
  5035.                  change; details below.  
  5036.  
  5037.                  The drawflag parameter specifies whether the object is to be
  5038.                  visually updated on the screen, use one of the following:
  5039.  
  5040.                    OBJ_NODRAW   (0) -    Don't update the screen.
  5041.                    OBJ_WITHDRAW (1) -    Update the screen.
  5042.                    OBJ_CLIPDRAW (2) -    Update the screen with clipping.
  5043.  
  5044.                  The cliprect parameter is an optional pointer to a rectangle
  5045.                  which will be used to clip the redraw of the object.  This
  5046.                  parameter is only used when the drawflag parameter is equal
  5047.                  to OBJ_CLIPDRAW.
  5048.  
  5049.        Returns:  Nothing.
  5050.  
  5051.        See Also:
  5052.  
  5053.        Details:  This function provides a simple way to change the object
  5054.                  state bits for any object.
  5055.  
  5056.                  If the high bit of the newstate parameter is set, an AND is
  5057.                  used to mask off bits in the object flags.  If the high bit
  5058.                  is not set, an OR is used to set bits in the object flags. 
  5059.                  This allows a newstate value of SELECTED to set the bit, and
  5060.                  a value of ~SELECTED to unset it.
  5061.  
  5062.                  When the drawflag parameter is non-zero, an objc_draw() call
  5063.                  is automatically done after the flags are changed.  The
  5064.                  objc_draw() is always done starting at object and drawing to
  5065.                  MAX_DEPTH, and the draw is clipped to the on-screen
  5066.                  rectangle of the dialog that contains it.  
  5067.  
  5068.                  When your dialog is in a window or another situation in
  5069.                  which you might need to clip the redraw, use the
  5070.                  OBJ_CLIPDRAW option, and provide a pointer to the clipping
  5071.                  rectangle.  If the draw option is not CLIPDRAW, the clip
  5072.                  pointer need not be specified.
  5073.  
  5074.        Source:   aesfuncs\objstchg.c
  5075.  
  5076.        
  5077.        ======================================================================
  5078.        GemFast v1.8                                                   Page 73
  5079.  
  5080.  
  5081.  
  5082.  
  5083.  
  5084.  
  5085.  
  5086.  
  5087.  
  5088.  
  5089.  
  5090.        int     obj_udthermo(OBJECT *ptree, int object, int increments,
  5091.                             GRECT *pcliprect)
  5092.        ______________________________________________________________________
  5093.  
  5094.        Summary:  Update the increment count on a G_THERMO object, with
  5095.                  optional redraw.
  5096.  
  5097.        Input:    The ptree parameter is a pointer to the tree.
  5098.  
  5099.                  The object parameter is the index of the G_THERMO object.
  5100.  
  5101.                  The increments parameter is the new increment count for the
  5102.                  object, or one of the following special values:
  5103.  
  5104.                    OBJ_TINCREMENT -  Add one to the current increment count.
  5105.                    OBJ_TINQUIRE   -  Return current increment count without
  5106.                                      changing it.
  5107.  
  5108.                  The pcliprect parameter, if non-NULL, specifies the clipping
  5109.                  rectangle for the redraw.  If NULL, no redraw is done.  If
  5110.                  you need no special clipping, pass &gl_rwdesk.
  5111.  
  5112.        Returns:  The increment count that was current before the call.
  5113.  
  5114.        See Also: obj_mkthermo()
  5115.  
  5116.        Details:  This function updates the increment count on a G_THERMO
  5117.                  object, and optionally redraws the object using the new
  5118.                  count.
  5119.  
  5120.                  If increments is zero or greater, the G_THERMO increment
  5121.                  count is set to increments.  If it's OBJ_TINCREMENT, this
  5122.                  function adds one to the current count.  The increment count
  5123.                  is clipped to the maximum number of increments set when the
  5124.                  G_THERMO was created or modified by obj_mkthermo().
  5125.  
  5126.                  In general, the OBJ_TINCREMENT (increment by one tick) value
  5127.                  should be the most common value passed for increments. 
  5128.                  Another useful technique is to set the G_THERMO to 100
  5129.                  increments and use it to represent percentage of completion
  5130.                  of a task.
  5131.  
  5132.                  If you pass a NULL pointer for a clipping rectangle, the
  5133.                  G_THERMO increment count is updated internally, but the
  5134.                  object is not updated on the screen.  This can be handy for
  5135.                  zeroing the increment count before displaying the dialog. 
  5136.  
  5137.        Example:  To report progress (using your own custom dialog box) as you
  5138.                  do something to each track of a floppy disk, you might use
  5139.  
  5140.  
  5141.  
  5142.        
  5143.        ======================================================================
  5144.        GemFast v1.8                                                   Page 74
  5145.  
  5146.  
  5147.  
  5148.  
  5149.  
  5150.  
  5151.  
  5152.  
  5153.                  code such as the following:
  5154.  
  5155.                      OBJECT  *pdialog;
  5156.  
  5157.                      rsc_gtrees(PROGRESS, &pdialog, -1);
  5158.                      if (!obj_mkthermo(pdialog, THERMOBAR, numtracks))
  5159.                          complain_and_die();
  5160.                      frm_dial(FRM_DSTART|FRM_DDRAW, pdialog, 0);
  5161.                      for (i = 0; i < numtracks; ++i) {
  5162.                          do_something_to_disk_track(i);
  5163.                          obj_udthermo(pdialog, THERMOBAR, 
  5164.                                          OBJ_TINCREMENT, &gl_rwdesk);
  5165.                      }
  5166.                      frm_dialog(FRM_DFINISH, pdialog, 0);
  5167.  
  5168.        Source:   aesfuncs\objtherm.c
  5169.  
  5170.  
  5171.  
  5172.  
  5173.        int     obj_xtfind(OBJECT *ptree, int parent, int xtype)
  5174.        ______________________________________________________________________
  5175.  
  5176.        Summary:  Finds the object with the specified extended object type.
  5177.  
  5178.        Input:    The ptree parameter is a pointer to the tree.
  5179.  
  5180.                  The parent parameter is the index of the parent which
  5181.                  contains the objects to be scanned.
  5182.  
  5183.                  The xtype parameter specifies the extended object type to
  5184.                  search for.
  5185.  
  5186.        Returns:  The index of the object having the specified extended type,
  5187.                  or NO_OBJECT (-1) if nothing was found.
  5188.  
  5189.        See Also: obj_bmbuttons() rsc_sxtypes()
  5190.  
  5191.        Details:  This function scans the children of the specified parent
  5192.                  object.  It compares the extended object type in each child
  5193.                  to the specified xtype, and returns the index of the first
  5194.                  object which matches.  If none of the children have the
  5195.                  specified extended type, NO_OBJECT is returned.
  5196.  
  5197.                  Extended object types are stored in the upper byte of the
  5198.                  ob_type word.  GEM only uses the lower 8 bits of the ob_type
  5199.                  value, and ignores any value in the upper 8 bits.  All
  5200.                  GemFast library routines which look at or set the ob_type
  5201.                  field also work with the lower 8 bits, and ignore (or
  5202.                  preserve) the upper 8 bits.
  5203.  
  5204.  
  5205.  
  5206.  
  5207.  
  5208.        
  5209.        ======================================================================
  5210.        GemFast v1.8                                                   Page 75
  5211.  
  5212.  
  5213.  
  5214.  
  5215.  
  5216.  
  5217.  
  5218.  
  5219.                  So, you can stuff any 8-bit value you want into the upper 8
  5220.                  bits of the ob_type word.  There's a zillion things you can
  5221.                  do with it.  
  5222.  
  5223.        Source:   aesfuncs\objxtfind.c
  5224.  
  5225.  
  5226.  
  5227.  
  5228.        void    obj_xywh(OBJECT *ptree, int object, GRECT *prect)
  5229.        ______________________________________________________________________
  5230.  
  5231.        Summary:  Get the xywh values for an object.
  5232.  
  5233.        Input:    The ptree parameter is a pointer to the object tree.
  5234.  
  5235.                  The object parameter is the index of the object.
  5236.  
  5237.                  The prect parameter is a pointer to the rectangle into which
  5238.                  the object's xywh values are returned.
  5239.  
  5240.        Returns:  Nothing.
  5241.  
  5242.        See Also: obj_offxywh() obj_clcalc() 
  5243.  
  5244.        Details:  This function gets the xywh values for the object.  The
  5245.                  values returned are straight from the object; they are
  5246.                  relative to the object's parent, not to the screen.
  5247.  
  5248.        Source:   aesfuncs\objoxywh.c
  5249.  
  5250.  
  5251.  
  5252.  
  5253.  
  5254.  
  5255.  
  5256.  
  5257.  
  5258.  
  5259.  
  5260.  
  5261.  
  5262.  
  5263.  
  5264.  
  5265.  
  5266.  
  5267.  
  5268.  
  5269.  
  5270.  
  5271.  
  5272.  
  5273.  
  5274.        
  5275.        ======================================================================
  5276.        GemFast v1.8                                                   Page 76
  5277.  
  5278.  
  5279.  
  5280.  
  5281.  
  5282.  
  5283.  
  5284.  
  5285.        Rectangle Calulations Library
  5286.  
  5287.  
  5288.                  The rectangle calculations library contains functions which
  5289.                  calculate common permutations of rectangles for you.  
  5290.  
  5291.                  In reading the descriptions of these functions, it is
  5292.                  important for you to keep in mind that these functions never
  5293.                  affect pixels; they work only with the rectangle structures
  5294.                  that describe areas of pixels.  (Sometimes the wording gets
  5295.                  confusing.  "Copies a rectangle" means the xywh values are
  5296.                  copied, not the pixels the rectangle describes.)
  5297.  
  5298.  
  5299.  
  5300.  
  5301.        void    rc_confine(void *boundrect, void *destrect)
  5302.        ______________________________________________________________________
  5303.  
  5304.        Summary:  Confine a rectangle to the inside of another rectangle.
  5305.  
  5306.        Input:    The boundrect parameter is a pointer to the boundary
  5307.                  rectangle within which the destination is confined.
  5308.  
  5309.                  The destrect parameter is a pointer to the destination
  5310.                  rectangle.  This rectangle supplies input values and
  5311.                  receives the results of the calculation; details below.
  5312.  
  5313.        Returns:  Nothing.
  5314.  
  5315.        See Also: frm_confine()
  5316.  
  5317.        Details:  This function forces the destination rectangle to be
  5318.                  confined within the boundary rectangle.  
  5319.  
  5320.                  On entry, the destination rectangle describes an initial
  5321.                  xywh area.  If any part of that area is outside the boundary
  5322.                  rectangle, the x and y values of the destination are
  5323.                  adjusted to keep it within the boundary.  
  5324.  
  5325.                  The width and height of the destination are never changed. 
  5326.                  It assumed (but not at all required) that the destination
  5327.                  rectangle will fit within the boundary.
  5328.  
  5329.                  If the destination rectangle is wider or taller than the
  5330.                  boundary, it is aligned with the upper or left corner of the
  5331.                  boundary in that dimension.  In other words, if the boundary
  5332.                  were the physical screen, the x/y values would never be set
  5333.                  to negative values.  This allows you to call this function
  5334.                  to align rectangle then call rc_intersect() to clip if
  5335.                  clipping is a requirement.
  5336.  
  5337.        Example:  Suppose you want to center a window over the current mouse
  5338.                  location.  You get the mouse x/y and set the window
  5339.  
  5340.        
  5341.        ======================================================================
  5342.        GemFast v1.8                                                   Page 77
  5343.  
  5344.  
  5345.  
  5346.  
  5347.  
  5348.  
  5349.  
  5350.  
  5351.                  rectangle's x/y so that it's centered over the mouse
  5352.                  location.  If the mouse was near the edge of the screen, the
  5353.                  window's xywh might now describe some off-screen area, so
  5354.                  you do:
  5355.  
  5356.                      rc_confine(&gl_rwdesk, &windrect);
  5357.                      winx_set(whandle, WF_CURRXYWH, &windrect);
  5358.  
  5359.                  This forces the edges of the window to align with the
  5360.                  desktop if the window would have been partly off-screen
  5361.                  before the call.  You know the window isn't bigger than the
  5362.                  desktop, so this sequence will always force the entire
  5363.                  window to appear on-screen.
  5364.  
  5365.        Source:   aesfuncs\rcconfin.c
  5366.  
  5367.  
  5368.  
  5369.  
  5370.        void    rc_copy(void *sourcerect, void *destrect)
  5371.        ______________________________________________________________________
  5372.  
  5373.        Summary:  Copy the source rectangle to the destination rectangle.
  5374.  
  5375.        Input:    The sourcerect parameter is a pointer to the source
  5376.                  rectangle.
  5377.  
  5378.                  The destrect parameter is a pointer to the destination
  5379.                  rectangle.
  5380.  
  5381.        Returns:  Nothing.
  5382.  
  5383.        See Also:
  5384.  
  5385.        Details:  This copies a rectangle, or more accurately, 8 bytes of
  5386.                  word-aligned data.
  5387.  
  5388.        Source:   aesutil.c\rccopy.c  
  5389.                  aesutil.s\rccopy.s
  5390.  
  5391.  
  5392.  
  5393.  
  5394.        int    rc_equal(void *rect1, void *rect2)
  5395.        ______________________________________________________________________
  5396.  
  5397.        Summary:  Returns TRUE if two rectangles are identical.
  5398.  
  5399.        Input:    The rect1 and rect2 parameters are pointers to the
  5400.                  rectangles to be compared.
  5401.  
  5402.        Returns:  TRUE (non-zero) if the rectangles are identical, FALSE (0)
  5403.                  if they're not.
  5404.  
  5405.  
  5406.        
  5407.        ======================================================================
  5408.        GemFast v1.8                                                   Page 78
  5409.  
  5410.  
  5411.  
  5412.  
  5413.  
  5414.  
  5415.  
  5416.  
  5417.        See Also:
  5418.  
  5419.        Details:  For the rectangles to be identical, all four values (xywh)
  5420.                  must be equal.  More accurately, this function compares 8
  5421.                  bytes of word-aligned data.
  5422.  
  5423.        Source:   aesutil.c\rcequal.c
  5424.                  aesutil.s\rcequal.s
  5425.  
  5426.  
  5427.  
  5428.  
  5429.        GRECT * rc_gadjust(GRECT *prect, int hadjust, int vadjust)
  5430.        ______________________________________________________________________
  5431.  
  5432.        Summary:  Adjust the size of a GRECT rectangle.
  5433.  
  5434.        Input:    The prect parameter is a pointer to the rectangle to be
  5435.                  adjusted.
  5436.  
  5437.                  The hadjust parameter is the number of pixels to adjust by
  5438.                  in the horizontal direction.  Positive values enlarge the
  5439.                  rectangle; negative values shrink it.
  5440.  
  5441.                  The vadjust parameter is the number of pixels to adjust by
  5442.                  in the vertical direction.  Positive values enlarge the
  5443.                  rectangle; negative values shrink it.
  5444.  
  5445.        Returns:  The pointer to the rectangle.
  5446.  
  5447.        See Also: rc_vadjust()
  5448.  
  5449.        Details:  This function makes a GRECT rectangle describe a larger or
  5450.                  smaller area.  The rectangle remains centered on its
  5451.                  original location, and grows or shrinks equally on each side
  5452.                  in the adjusted dimension(s).
  5453.  
  5454.                  The x/y locations are never allowed to go negative (they are
  5455.                  clipped to zero).  The w/h sizes are never allowed to fall
  5456.                  below 1.
  5457.  
  5458.        Source:   aesutil.s\rcadjust.s
  5459.                  aesutil.c\rcadjust.c
  5460.  
  5461.  
  5462.  
  5463.  
  5464.  
  5465.  
  5466.  
  5467.  
  5468.  
  5469.  
  5470.  
  5471.  
  5472.        
  5473.        ======================================================================
  5474.        GemFast v1.8                                                   Page 79
  5475.  
  5476.  
  5477.  
  5478.  
  5479.  
  5480.  
  5481.  
  5482.  
  5483.        VRECT *  rc_gtov(GRECT *pgrect, VRECT *pvrect)
  5484.        ______________________________________________________________________
  5485.  
  5486.        Summary:  Convert a GRECT rectangle to a VRECT rectangle.
  5487.  
  5488.        WARNING:  There was a major change in this function's behavior in v1.8
  5489.                  that will affect existing code; details below.
  5490.  
  5491.        Input:    The pgrect parameter is a pointer to the source GRECT.
  5492.  
  5493.                  The pvrect parameter is a pointer to the destination VRECT.
  5494.  
  5495.        Returns:  The pointer to the destination VRECT.
  5496.  
  5497.        See Also: rc_vtog()
  5498.  
  5499.        Details:  The source GRECT is converted to the equivalent VRECT.  Do
  5500.                  NOT specify the same rectangle for source and destination.
  5501.  
  5502.                  A GRECT describes an area by x, y, width and height.  A
  5503.                  VRECT describes an area by the x and y coordinates of
  5504.                  diagonally opposite corners.  This function translates a
  5505.                  GRECT to a VRECT as follows:
  5506.  
  5507.                      pvrect->v_x1 = pgrect->g_x;
  5508.                      pvrect->v_y1 = pgrect->g_y;
  5509.                      pvrect->v_x2 = pgrect->g_x + pgrect->g_w - 1;
  5510.                      pvrect->v_y2 = pgrect->g_y + pgrect->g_h - 1;
  5511.  
  5512.                  GemFast versions prior to v1.8 did not apply the -1
  5513.                  correction to the second pair of coordinates.  This was just
  5514.                  plain wrong, and it had to be fixed even though you may now
  5515.                  have to go remove some -1 expressions in your existing code
  5516.                  where you were compensating for the broken behavior of the
  5517.                  old versions.  ::sigh::  Sorry.
  5518.  
  5519.        Source:   aesutil.s\rcgtov.s
  5520.                  aesutil.c\rcgtov.c
  5521.  
  5522.  
  5523.  
  5524.  
  5525.        int     rc_intersect(GRECT *sourcerect, GRECT *destrect)
  5526.        ______________________________________________________________________
  5527.  
  5528.        Summary:  Calculate the intersecting portion of two rectangles.
  5529.  
  5530.        WARNING:  There was a minor change in this function's behavior in v1.8
  5531.                  that could affect existing code; details below.
  5532.  
  5533.        Input:    The sourcerect parameter is a pointer to the source (or
  5534.                  clipping) rectangle.
  5535.  
  5536.                  The destrect parameter is a pointer to the destination
  5537.  
  5538.        
  5539.        ======================================================================
  5540.        GemFast v1.8                                                   Page 80
  5541.  
  5542.  
  5543.  
  5544.  
  5545.  
  5546.  
  5547.  
  5548.  
  5549.                  rectangle.  The destination rectangle is used for input and
  5550.                  output.
  5551.  
  5552.        Returns:  TRUE (1) if the two rectangles intersect, or FALSE (0) if
  5553.                  they do not intersect.  When the return value is FALSE, the
  5554.                  contents of the destination rectangle are undetermined.
  5555.  
  5556.        See Also:
  5557.  
  5558.        Details:  You can think of this function as clipping the destination
  5559.                  rectangle against the area of the source.  
  5560.  
  5561.                  On entry, the destination rectangle describes an area that
  5562.                  may or may not have pixels in common with the source (or
  5563.                  clipping) rectangle.  This function modifies the destination
  5564.                  rectangle to describe the area where the two rectangles
  5565.                  intersect.  If they don't intersect at all, this function
  5566.                  returns FALSE, and the destination rectangle is left in an
  5567.                  undetermined state.
  5568.  
  5569.                  This function is typically used in window redraw loops, to
  5570.                  process the window rectangle list.  It can also be used in
  5571.                  general-purpose drawing situations, especially to generate a
  5572.                  clip rectangle to keep a blit from going outside the window
  5573.                  work area or off the screen.
  5574.  
  5575.                  This function does NOT clip to the physical screen
  5576.                  automatically.  Negative values in the returned x and y
  5577.                  coordinates are possible if negative values existed in the
  5578.                  inputs.
  5579.  
  5580.                  In GemFast versions prior to v1.8, this function would
  5581.                  return TRUE if the destination rectangle had a zero width or
  5582.                  height.  That doesn't make sense; if width or height is
  5583.                  zero, there's obviously no intersection of the two
  5584.                  rectangles (they may abut rather than intersect).  Starting
  5585.                  with v1.8, a zero width or height results in a FALSE return
  5586.                  value.  This shouldn't break any existing code (and should
  5587.                  make your window redraw loops a bit simpler) but as a change
  5588.                  in behavior it bears mentioning.
  5589.  
  5590.        Source:   aesutil.s\rcinters.s
  5591.                  aesutil.c\rcinters.c
  5592.  
  5593.  
  5594.  
  5595.  
  5596.        int    rc_ptinrect(GRECT *prect, int x, int y)
  5597.        ______________________________________________________________________
  5598.  
  5599.        Summary:  Determine whether a point is inside a rectangle.
  5600.  
  5601.        Input:    The prect parameter is a pointer to the rectangle.
  5602.  
  5603.  
  5604.        
  5605.        ======================================================================
  5606.        GemFast v1.8                                                   Page 81
  5607.  
  5608.  
  5609.  
  5610.  
  5611.  
  5612.  
  5613.  
  5614.  
  5615.                  The x and y parameters are the coordinates of the point to
  5616.                  be checked against the rectangle.
  5617.  
  5618.  
  5619.        Returns:  TRUE if the point is inside the rectangle, FALSE if not.  A
  5620.                  point on the boundary of the rectangle is considered to be
  5621.                  inside it.
  5622.  
  5623.        See Also:
  5624.  
  5625.        Details:  This is useful for determining whether the mouse is
  5626.                  currently located within some arbitrary area.
  5627.  
  5628.        Source:   aesfuncs\rcptinre.c
  5629.  
  5630.  
  5631.  
  5632.  
  5633.        GRECT *  rc_scale(GRECT *sourcerect, GRECT *destrect, int percent)
  5634.        ______________________________________________________________________
  5635.  
  5636.        Summary:  This function calculates a scaled copy of a rectangle. 
  5637.  
  5638.        Input:    The sourcerect parameter is a pointer to the source
  5639.                  rectangle.
  5640.  
  5641.                  The destrect parameter is a pointer to the destination
  5642.                  rectangle.  
  5643.  
  5644.                  The percent parameter is the scaling factor.
  5645.  
  5646.        Returns:  The pointer to the destination rectangle.
  5647.  
  5648.        See Also:
  5649.  
  5650.        Details:  This function calculates a scaled copy of a rectangle.  The
  5651.                  new rectangle describes an area larger or smaller than the
  5652.                  original, and is centered over or within the original
  5653.                  rectangle's area.
  5654.  
  5655.                  The percent parameter determines the scaling.  A value of
  5656.                  100 results in no size change.  A value of 200 doubles the
  5657.                  rectangle's area, a value of 50 halves it, a value of 5
  5658.                  yields one twentieth the original size, and so on.  The
  5659.                  resulting rectangle's width and height will never be less
  5660.                  than 1.
  5661.  
  5662.                  As an interesting side effect, using a percent value of 0
  5663.                  gives the center point of the source rectangle in the result
  5664.                  rectangle's x/y fields (and 1 in its w/h fields).  
  5665.  
  5666.        Source:   aesutil.s\rcscale.s
  5667.                  aesutil.c\rcscale.c
  5668.  
  5669.  
  5670.        
  5671.        ======================================================================
  5672.        GemFast v1.8                                                   Page 82
  5673.  
  5674.  
  5675.  
  5676.  
  5677.  
  5678.  
  5679.  
  5680.  
  5681.  
  5682.  
  5683.        void     rc_union(GRECT *sourcerect, GRECT *destrect)
  5684.        ______________________________________________________________________
  5685.  
  5686.        Summary:  Computes a single rectangle that encompasses the area of
  5687.                  both the original rectangles.
  5688.  
  5689.        Input:    The sourcerect parameter is a pointer to the source
  5690.                  rectangle.
  5691.  
  5692.                  The destrect parameter is a pointer to the destination
  5693.                  rectangle.  The destination rectangle is used for input and
  5694.                  output.
  5695.  
  5696.        Returns:  Nothing.
  5697.  
  5698.        See Also:
  5699.  
  5700.        Details:  This function calculates the single large rectangle that
  5701.                  encompasses all the area of both rectangles.
  5702.  
  5703.                  This function does NOT clip to the physical screen
  5704.                  automatically.  Negative values in the returned x and y
  5705.                  coordinates are possible if negative values existed in the
  5706.                  inputs.
  5707.  
  5708.        Source:   aesutil.s\rcunion.s
  5709.                  aesutil.c\rcunion.c
  5710.  
  5711.  
  5712.  
  5713.  
  5714.        VRECT *  rc_vadjust(VRECT *prect, int hadjust, int vadjust)
  5715.        ______________________________________________________________________
  5716.  
  5717.        Summary:  Adjust the size of a VRECT rectangle.
  5718.  
  5719.        Input:    The prect parameter is a pointer to the rectangle to be
  5720.                  adjusted.
  5721.  
  5722.                  The hadjust parameter is the number of pixels to adjust by
  5723.                  in the horizontal direction.  Positive values enlarge the
  5724.                  rectangle; negative values shrink it.
  5725.  
  5726.                  The vadjust parameter is the number of pixels to adjust by
  5727.                  in the vertical direction.  Positive values enlarge the
  5728.                  rectangle; negative values shrink it.
  5729.  
  5730.        Returns:  The pointer to the rectangle.
  5731.  
  5732.        See Also: rc_gadjust()
  5733.  
  5734.        Details:  This function makes a VRECT rectangle describe a larger or
  5735.  
  5736.        
  5737.        ======================================================================
  5738.        GemFast v1.8                                                   Page 83
  5739.  
  5740.  
  5741.  
  5742.  
  5743.  
  5744.  
  5745.  
  5746.  
  5747.                  smaller area.  The rectangle remains centered on its
  5748.                  original location, and grows or shrinks equally on each side
  5749.                  in the adjusted dimension(s).
  5750.  
  5751.                  The x/y locations are never allowed to go negative (they are
  5752.                  clipped to zero).  The w/h sizes are never allowed to fall
  5753.                  below 1.
  5754.  
  5755.        Source:   aesutil.s\rcadjust.s
  5756.                  aesutil.c\rcadjust.c
  5757.  
  5758.  
  5759.  
  5760.  
  5761.        GRECT *  rc_vtog(VRECT *pvrect, GRECT *pgrect)
  5762.        ______________________________________________________________________
  5763.  
  5764.        Summary:  Convert a VRECT rectangle to a GRECT rectangle.
  5765.  
  5766.        WARNING:  There was a major change in this function's behavior in v1.8
  5767.                  that will affect existing code; details below.
  5768.  
  5769.        Input:    The pvrect parameter is a pointer to the source VRECT.
  5770.  
  5771.                  The pgrect parameter is a pointer to the destination GRECT.
  5772.  
  5773.        Returns:  The pointer to the destination GRECT.
  5774.  
  5775.        See Also: rc_gtov()
  5776.  
  5777.        Details:  The source VRECT is converted to the equivalent GRECT.  Do
  5778.                  NOT specify the same rectangle for source and destination.
  5779.  
  5780.                  A VRECT describes an area by the x and y coordinates of
  5781.                  diagonally opposite corners.  A GRECT describes an area by
  5782.                  x, y, width and height.  This function translates a VRECT to
  5783.                  a GRECT as follows:
  5784.  
  5785.                      pgrect->g_x = pvrect->v_x1;
  5786.                      pgrect->g_y = pvrect->v_y1;
  5787.                      pgrect->g_w = pvrect->v_x1 - pvrect->g_x2 + 1;
  5788.                      pgrect->g_h = pvrect->v_y1 - pvrect->g_y2 + 1;
  5789.  
  5790.                  GemFast versions prior to v1.8 did not apply the +1
  5791.                  correction to the second pair of coordinates.  This was just
  5792.                  plain wrong, and it had to be fixed even though you may now
  5793.                  have to go remove some +1 expressions in your existing code
  5794.                  where you were compensating for the broken behavior of the
  5795.                  old versions.  ::sigh::  Sorry.
  5796.  
  5797.        Source:   aesutil.s\rcgtov.s
  5798.                  aesutil.c\rcgtov.c
  5799.  
  5800.  
  5801.  
  5802.        
  5803.        ======================================================================
  5804.        GemFast v1.8                                                   Page 84
  5805.  
  5806.  
  5807.  
  5808.  
  5809.  
  5810.  
  5811.  
  5812.  
  5813.        Resource Library
  5814.  
  5815.  
  5816.                  The resource library contains functions which manipulate an
  5817.                  entire object tree, or a list of objects in a tree.  It
  5818.                  includes functions that simplify access to the strings in
  5819.                  your dialogs, functions that alter the appearance of the
  5820.                  buttons in a dialog, and a few miscellaneous things.
  5821.  
  5822.  
  5823.  
  5824.  
  5825.        int     rsc_cubuttons(OBJECT *ptree)
  5826.        ______________________________________________________________________
  5827.  
  5828.        Summary:  Change all buttons in a dialog tree to CUA-style buttons.
  5829.  
  5830.        Input:    The ptree parameter is a pointer to the dialog tree to be
  5831.                  modified.
  5832.  
  5833.        Returns:  Zero for success, or a negative (TOS) error code.
  5834.  
  5835.        See Also: rsc_rrbuttons()
  5836.  
  5837.        Details:  This function modifies the visual appearance of all non-exit
  5838.                  buttons in a dialog, transforming them to extended G_USERDEF
  5839.                  objects and supplying a custom drawing function.  The visual
  5840.                  style of selection (on/off) and radio buttons is similar to
  5841.                  the CUA standard used by Windows 3 and other systems.  Exit
  5842.                  buttons aren't  changed, because GEM exit buttons are
  5843.                  already CUA-ish.
  5844.  
  5845.                  This function lets you use a standard GEM resource editor to
  5846.                  create dialogs using GEM buttons.  The only restriction on
  5847.                  resource design is that your buttons' boxes should be at
  5848.                  least 3 characters wider than the strings they contain.  A
  5849.                  CUA-style selection or radio button includes a graphic box
  5850.                  and whitespace equal to 3 character widths in front of the
  5851.                  displayed button string.
  5852.  
  5853.                  This function allocates a block of memory to contain the
  5854.                  XUSERBLK structures that it attaches to the button objects. 
  5855.                  If the allocation fails, ENSMEM (-39) is returned.  It is
  5856.                  also possible to get a return value of -35 (no more handles)
  5857.                  if the VDI shared workstation can't be opened.
  5858.  
  5859.                  Each selection or radio button object in the dialog tree is
  5860.                  transformed into an extended G_USERDEF object.  The
  5861.                  description of obj_mxuserdef() contains more details on
  5862.                  extended G_USERDEF objects.  The main implication of this
  5863.                  transformation is that the button's string pointer is moved
  5864.                  from the object's ob_spec field to the XUSERBLK ob_spec
  5865.                  field.  If you use rsc_gstrings() and/or rsc_sstrings() as
  5866.                  your sole access to the button's string, you don't have to
  5867.  
  5868.        
  5869.        ======================================================================
  5870.        GemFast v1.8                                                   Page 85
  5871.  
  5872.  
  5873.  
  5874.  
  5875.  
  5876.  
  5877.  
  5878.  
  5879.                  worry about this at all.
  5880.  
  5881.                  Other than the button string pointer, you can continue to
  5882.                  access the buttons in the usual way, directly accessing the
  5883.                  ob_flags and ob_state fields as needed.  In addition, you
  5884.                  can use the extended object type as you wish; this function
  5885.                  changes the lower 8 bits of the ob_type field to G_USERDEF,
  5886.                  but leaves the upper 8 bits alone.
  5887.  
  5888.                  I would like to recommend that you don't mix button styles
  5889.                  in the same application.  Pick one style, (GEM, CUA, or RR)
  5890.                  and use it for all your dialogs.
  5891.  
  5892.        Source:   aesfuncs\rsccubtn.c
  5893.  
  5894.  
  5895.  
  5896.  
  5897.        void    rsc_gstrings(OBJECT *ptree, int object, char **ppstr, ...)
  5898.        ______________________________________________________________________
  5899.  
  5900.        Summary:  Get the string pointers for one or more string-related
  5901.                  objects in a dialog tree.
  5902.  
  5903.        Input:    The ptree parameter is a pointer to the dialog tree
  5904.                  containing the string-related objects.
  5905.  
  5906.                  The object parameter is the index of the first object for
  5907.                  which you want to retrieve the string pointer.
  5908.  
  5909.                  The ppstr parameter is a pointer to your variable
  5910.                  (char* type).  The string pointer for the object is stored
  5911.                  here.
  5912.  
  5913.                  The ... parameters are additional object/ppstr pairs.  Use
  5914.                  an object number of -1 to indicate the end of the list.
  5915.  
  5916.        Returns:  Nothing.
  5917.  
  5918.        See Also: rsc_sstrings() obj_ppstring()
  5919.  
  5920.        Details:  This allows you to easily initialize your local string
  5921.                  pointers to point at string-related objects in a dialog
  5922.                  tree.  The description of the obj_ppstring() function
  5923.                  contains details on what objects are string-related.
  5924.  
  5925.                  You must specify at least one object/ppstr pair following
  5926.                  the tree pointer in the call.  You can specify any number of
  5927.                  pairs following the first one to retrieve the pointers for
  5928.                  more than one object with a single call.  Specify -1 for the
  5929.                  index following the last pair.  (There's no need to supply a
  5930.                  pointer to go with the -1 object index.)  
  5931.  
  5932.                  This function understands how to find the real string
  5933.  
  5934.        
  5935.        ======================================================================
  5936.        GemFast v1.8                                                   Page 86
  5937.  
  5938.  
  5939.  
  5940.  
  5941.  
  5942.  
  5943.  
  5944.  
  5945.                  pointer for each of string-related object type.  It copes
  5946.                  with the INDIRECT flag.  It understands extended G_USERDEF
  5947.                  objects, where ob_spec has been moved into the XUSERBLK.
  5948.  
  5949.                  This function gives you pointers which point into the
  5950.                  resource data area.  If you modify the strings using these
  5951.                  pointers, please remember that your resource editor has only
  5952.                  allocated enough space in the resource data to hold the
  5953.                  strings as you typed them when you built the object.  In
  5954.                  other words, you can define a button as "OK", and then at
  5955.                  runtime use this function to get a pointer to the button
  5956.                  text.  But, if you do something like
  5957.                      strcpy(buttonptr, "Not Okay"); 
  5958.                  then you end up corrupting the resource data, because you
  5959.                  copied an 8-character string into a space only 2 characters
  5960.                  wide.  
  5961.  
  5962.                  You can avoid this modify-in-place problem by defining your
  5963.                  strings big enough in the resource editor, or by using
  5964.                  rsc_sstrings() to make the objects point to strings
  5965.                  allocated within your program rather than working with the
  5966.                  strings directly in the resource data area.  In this case,
  5967.                  you can define dummy strings (I use "x") in the resource
  5968.                  editor to avoid wasting space, since the strings you define
  5969.                  are not used at runtime anyway after you use rsc_sstrings()
  5970.                  to point objects at your program-defined strings.
  5971.  
  5972.        Example:  To retrieve the string pointers for a button and a text
  5973.                  object, use code such as the following:
  5974.  
  5975.                      char *editstring;
  5976.                      char *btnstring;
  5977.           
  5978.                      void dial_init()
  5979.                      {
  5980.                          rsc_gstrings(mydialog, 
  5981.                                          EDITOBJ, &editstring,
  5982.                                          BUTTON1, &btnstring,
  5983.                                          -1);
  5984.                          *editstring = 0; // empty the edit string
  5985.                          strcpy(btnstring, " Go "); // set the button text
  5986.                      }
  5987.  
  5988.        Source:   aesfuncs\rscgstr.c
  5989.  
  5990.  
  5991.  
  5992.  
  5993.  
  5994.  
  5995.  
  5996.  
  5997.  
  5998.  
  5999.  
  6000.        
  6001.        ======================================================================
  6002.        GemFast v1.8                                                   Page 87
  6003.  
  6004.  
  6005.  
  6006.  
  6007.  
  6008.  
  6009.  
  6010.  
  6011.        void    rsc_gtrees(int treeindex, OBJECT **pptree, ...)
  6012.        ______________________________________________________________________
  6013.  
  6014.        Summary:  Retrieve the pointers to one or more dialog trees within the
  6015.                  resource data area.
  6016.  
  6017.        Input:    The treeindex parameter is the index of the tree.  This is
  6018.                  the name you assigned the tree in the resource editor.
  6019.  
  6020.                  The pptree parameter is a pointer to your tree pointer
  6021.                  variable (OBJECT * type).
  6022.  
  6023.                  The ... parameters are additional treeindex/pptree pairs. 
  6024.                  Use an index value of -1 to indicate the end of the
  6025.                  parameter list.
  6026.  
  6027.        Returns:  Nothing.
  6028.  
  6029.        See Also:
  6030.  
  6031.        Details:  This function simplifies the process of getting your
  6032.                  resource tree pointers.  Typically, your program contains an
  6033.                  init routine which has a series of rsrc_gaddr() calls.  This
  6034.                  function allows you to replace that series of calls with a
  6035.                  single call.  
  6036.  
  6037.        Example:  If your resource data contains 3 trees, you might use:
  6038.  
  6039.                      OBJECT *menu;
  6040.                      OBJECT *maindialog;
  6041.                      OBJECT *selectdialog;
  6042.  
  6043.                      prg_init()
  6044.                      {
  6045.                          appl_init();
  6046.                          if (!rsrc_load("myrsc.rsc")) {
  6047.                              // complain and die
  6048.                          }
  6049.                          rsc_gtrees(MENUTREE, &menu,
  6050.                                     MAINTREE, &maindialog,
  6051.                                     SELCTONE, &selectdialog,
  6052.                                     -1);
  6053.                          menu_bar(menu, TRUE);
  6054.                          // etc
  6055.                      }
  6056.  
  6057.        Source:   aesfuncs\rscgtree.c
  6058.  
  6059.  
  6060.  
  6061.  
  6062.  
  6063.  
  6064.  
  6065.  
  6066.        
  6067.        ======================================================================
  6068.        GemFast v1.8                                                   Page 88
  6069.  
  6070.  
  6071.  
  6072.  
  6073.  
  6074.  
  6075.  
  6076.  
  6077.        int     rsc_rrbuttons(OBJECT *ptree)
  6078.        ______________________________________________________________________
  6079.  
  6080.        Summary:  Change all radio buttons in a dialog tree to display as
  6081.                  rounded-corner buttons.
  6082.  
  6083.        Input:    The ptree parameter is a pointer to the dialog tree to be
  6084.                  modified.
  6085.  
  6086.        Returns:  Zero for success, or a negative (TOS) error code.
  6087.  
  6088.        See Also: rsc_cubuttons()
  6089.  
  6090.        Details:  This function modifies the visual appearance of all radio
  6091.                  buttons in a dialog, transforming them to extended G_USERDEF
  6092.                  objects and supplying a custom drawing function which draws
  6093.                  radio buttons with rounded corners.  This gives the user
  6094.                  immediate visual cues as to which buttons are selection
  6095.                  (on/off) buttons and which are radio buttons.  The selection
  6096.                  buttons (not modified by this function) will display as
  6097.                  standard square-corner buttons, and radio buttons will have
  6098.                  rounded corners.
  6099.  
  6100.                  This function lets you use a standard GEM resource editor to
  6101.                  create dialogs using GEM buttons.  There are no restrictions
  6102.                  on the way you design your buttons.
  6103.  
  6104.                  This function allocates a block of memory to contain the
  6105.                  XUSERBLK structures that it attaches to the button objects. 
  6106.                  If the allocation fails, ENSMEM (-39) is returned.  It is
  6107.                  also possible to get a return value of -35 (no more handles)
  6108.                  if the VDI shared workstation can't be opened.
  6109.  
  6110.                  Each selection or radio button object in the dialog tree is
  6111.                  transformed into an extended G_USERDEF object.  The
  6112.                  description of obj_mxuserdef() contains more details on
  6113.                  extended G_USERDEF objects.  The main implication of this
  6114.                  transformation is that the button's string pointer is moved
  6115.                  from the object's ob_spec field to the XUSERBLK ob_spec
  6116.                  field.  If you use rsc_gstrings() and/or rsc_sstrings() as
  6117.                  your sole access to the button's string, you don't have to
  6118.                  worry about this at all.
  6119.  
  6120.                  Other than the button string pointer, you can continue to
  6121.                  access the buttons in the usual way, directly accessing the
  6122.                  ob_flags and ob_state fields as needed.  In addition, you
  6123.                  can use the extended object type as you wish; this function
  6124.                  changes the lower 8 bits of the ob_type field to G_USERDEF,
  6125.                  but leaves the upper 8 bits alone.
  6126.  
  6127.  
  6128.  
  6129.  
  6130.  
  6131.  
  6132.        
  6133.        ======================================================================
  6134.        GemFast v1.8                                                   Page 89
  6135.  
  6136.  
  6137.  
  6138.  
  6139.  
  6140.  
  6141.  
  6142.  
  6143.                  I would like to recommend that you don't mix button styles
  6144.                  in the same application.  Pick one style, (GEM, CUA, or RR)
  6145.                  and use it for all your dialogs.
  6146.  
  6147.        Source:   aesfuncs\rsrrubtn.c
  6148.  
  6149.  
  6150.  
  6151.  
  6152.        void    rsc_sstrings(OBJECT *ptree, int object, char *pstr, ...)
  6153.        ______________________________________________________________________
  6154.  
  6155.        Summary:  Set the string pointers for one or more string-related
  6156.                  objects in a dialog tree.
  6157.  
  6158.        Input:    The ptree parameter is a pointer to the dialog tree
  6159.                  containing the string-related objects.
  6160.  
  6161.                  The object parameter is the index of the first object for
  6162.                  which you want to set the string pointer.
  6163.  
  6164.                  The pstr parameter is a pointer to your string variable
  6165.                  (char [] or "" type).  This pointer is copied into the
  6166.                  string object's string pointer field (ob_spec, te_ptext,
  6167.                  etc).
  6168.  
  6169.                  The ... parameters are additional object/pstr pairs.  Use an
  6170.                  object number of -1 to indicate the end of the list.
  6171.  
  6172.        Returns:  Nothing.
  6173.  
  6174.        See Also: rsc_gstrings() obj_ppstring()
  6175.  
  6176.        Details:  This allows you to easily initialize string-related objects
  6177.                  in a dialog tree to point at strings defined within your
  6178.                  program.  The description of the obj_ppstring() function
  6179.                  contains details on what objects are string-related.
  6180.  
  6181.                  You must specify at least one object/pstr pair following the
  6182.                  tree pointer in the call.  You can specify any number of
  6183.                  pairs following the first one to retrieve the pointers for
  6184.                  more than one object with a single call.  Specify -1 for the
  6185.                  index following the last pair.  (There's no need to supply a
  6186.                  pointer to go with the -1 object index.)  
  6187.  
  6188.                  This function understands how to find the real string
  6189.                  pointer for each of string-related object type.  It copes
  6190.                  with the INDIRECT flag.  It understands extended G_USERDEF
  6191.                  objects, where ob_spec has been moved into the XUSERBLK.
  6192.  
  6193.                  This function attaches string data defined in your program
  6194.                  to string-related objects in your dialog trees.  This is
  6195.                  especially handy for editable text objects, because some
  6196.                  resource editors don't allocate enough space for the object
  6197.  
  6198.        
  6199.        ======================================================================
  6200.        GemFast v1.8                                                   Page 90
  6201.  
  6202.  
  6203.  
  6204.  
  6205.  
  6206.  
  6207.  
  6208.  
  6209.                  in the resource data.  If you define an editable text object
  6210.                  and supply a te_pvalid string that allows 20 chars of input,
  6211.                  but you define an initial string of "abc" for the field,
  6212.                  some resource editors will only allocate 3 bytes of resource
  6213.                  string space for the field.  When the user enters 20 chars
  6214.                  of data into the 3-byte field, other resource data gets
  6215.                  corrupted.  To avoid this, you can allocate a 20-byte
  6216.                  character array in your program, and use this function to
  6217.                  make the editable field's te_ptext pointer point at your
  6218.                  array instead of the 3-byte area in the resource data.
  6219.  
  6220.        Example:  To supply a local string constant for a G_STRING item, a
  6221.                  local character array for an editable item, and the text for
  6222.                  an icon, you might use code like this:
  6223.  
  6224.                      char editbuffer[20] = ""; // 20 bytes, starts empty
  6225.                      char iconname[] = "This is ICON #1"; // a silly name
  6226.           
  6227.                      void dial_init()
  6228.                      {
  6229.                          rsc_sstrings(mydialog, 
  6230.                                          EDITOBJ,  editbuffer,
  6231.                                          ICON1,    iconname,
  6232.                                          TITLESTR, "My dialog v1.1a",
  6233.                                          -1);
  6234.                      }
  6235.  
  6236.        Source:   aesfuncs\rscsstr.c
  6237.  
  6238.  
  6239.  
  6240.  
  6241.        void    rsc_sxtypes(OBJECT *ptree, int object, int xtype, ...)
  6242.        ______________________________________________________________________
  6243.  
  6244.        Summary:  Sets the extended object type in one or more objects.
  6245.  
  6246.        Input:    The ptree parameter is a pointer to the tree which contains
  6247.                  the objects.
  6248.  
  6249.                  The object parameter is the index of the first object for
  6250.                  which you want to set the extended object type.
  6251.  
  6252.                  The xtype parameter is the extended object type (a value
  6253.                  between 0x00 and 0xFF) to be set in the object.
  6254.  
  6255.                  The ... parameters are additional object/xtype pairs.  Use
  6256.                  an object number of -1 to indicate the end of the list.
  6257.  
  6258.        Returns:  Nothing.
  6259.  
  6260.        See Also: obj_bmbuttons() obj_xtfind() 
  6261.  
  6262.        Details:  This function sets the extended object type field in one or
  6263.  
  6264.        
  6265.        ======================================================================
  6266.        GemFast v1.8                                                   Page 91
  6267.  
  6268.  
  6269.  
  6270.  
  6271.  
  6272.  
  6273.  
  6274.  
  6275.                  more objects within a tree.  Extended object types are
  6276.                  discussed under the obj_bmbuttons() and obj_xtfind()
  6277.                  functions.  
  6278.  
  6279.                  Some resource editor programs let you set the extended type
  6280.                  when you create the resource, others don't allow that.  Use
  6281.                  this function to set the extended type values during program
  6282.                  startup when you can't set them in the resource editor.
  6283.  
  6284.        Source:   aesfuncs\rscsxtyp.c
  6285.  
  6286.  
  6287.  
  6288.  
  6289.        void    rsc_treefix(OBJECT *ptree)
  6290.        ______________________________________________________________________
  6291.  
  6292.        Summary:  Performs xywh fixup on all objects in a tree.
  6293.  
  6294.        Input:    The ptree parameter is a pointer to the tree which needs
  6295.                  resolution fixup.
  6296.  
  6297.        Returns:  Nothing.
  6298.  
  6299.        See Also:
  6300.  
  6301.        Details:  This function calls rsrc_obfix() for every object in the
  6302.                  tree.  It's just a shortcut for calling the GEM object fixup
  6303.                  for all objects in a tree, and does not provide any custom
  6304.                  resolution fixup, scaling, etc.
  6305.  
  6306.                  Use this function to do fixup on resource trees which are
  6307.                  embedded in your source code.  Do NOT use this function on
  6308.                  trees loaded via rsrc_load(), since that function
  6309.                  automatically applies resolution fixup as it loads the
  6310.                  resource data.
  6311.  
  6312.        Source:   aesfuncs\rsctrfix.c
  6313.  
  6314.  
  6315.  
  6316.  
  6317.  
  6318.  
  6319.  
  6320.  
  6321.  
  6322.  
  6323.  
  6324.  
  6325.  
  6326.  
  6327.  
  6328.  
  6329.  
  6330.        
  6331.        ======================================================================
  6332.        GemFast v1.8                                                   Page 92
  6333.  
  6334.  
  6335.  
  6336.  
  6337.  
  6338.  
  6339.  
  6340.  
  6341.        Window Library
  6342.  
  6343.  
  6344.                  The window library contains functions that work with windows
  6345.                  and window-related events.
  6346.  
  6347.  
  6348.  
  6349.  
  6350.  
  6351.        int    wnd_top(void)
  6352.        ______________________________________________________________________
  6353.  
  6354.        Summary:  Obtain the handle of the current top window.
  6355.  
  6356.        Input:    Nothing.
  6357.  
  6358.        Returns:  The handle of the currently-topped window.
  6359.  
  6360.        See Also:
  6361.  
  6362.        Details:  This function is a shortcut call for wind_get(0,WF_TOP,...),
  6363.                  since querying the current top window handle is something
  6364.                  GEM programs seem to do a lot.
  6365.  
  6366.        Source:   aesutil.s\wndtop.s
  6367.                  aesutil.c\wndtop.c
  6368.  
  6369.  
  6370.  
  6371.  
  6372.        void    wind_update(int flag)
  6373.        void    wnd_update(int flag)
  6374.        ______________________________________________________________________
  6375.  
  6376.        Summary:  Set or unset the window or mouse update flag, with stacked
  6377.                  call logic.
  6378.  
  6379.        NOTE:     A macro in GEMFAST.H automatically remaps your wind_update()
  6380.                  calls to wnd_update().
  6381.  
  6382.        Input:    The flag parameter is any of the GEM-defined flags for
  6383.                  wind_update().  (BEG_UPDATE, END_UPDATE, BEG_MCTRL,
  6384.                  END_MCTRL).
  6385.  
  6386.        Returns:  Nothing.
  6387.  
  6388.        See Also:
  6389.  
  6390.        Details:  This function causes wind_update() calls to be handled like
  6391.                  hide/show mouse calls:  3 BEG_UPDATE calls will require 3
  6392.                  END_UPDATE calls; only the 3rd END_UPDATE actually gets
  6393.                  passed to GEM.
  6394.  
  6395.  
  6396.        
  6397.        ======================================================================
  6398.        GemFast v1.8                                                   Page 93
  6399.  
  6400.  
  6401.  
  6402.  
  6403.  
  6404.  
  6405.  
  6406.  
  6407.                  This type of functionality is required in blackbox library
  6408.                  routines (such as GemFast itself), where the library routine
  6409.                  can't know whether wind_update() has already been called by
  6410.                  the application or not.  GEM will consider a single
  6411.                  END_UPDATE call sufficient to cancel any number of preceding
  6412.                  BEG_UPDATE calls.  That could result in a library routine
  6413.                  accidentally releasing the update flag before the
  6414.                  application was ready for it.  
  6415.  
  6416.                  This function keeps separate internal counters for the
  6417.                  UPDATE and MCTRL flags; the counter is incremented on each
  6418.                  BEG_whatever call, and decremented on each END_whatever
  6419.                  call.  It only passes a BEG_whatever call through if that
  6420.                  counter is currently at zero.  When it sees an END_whatever
  6421.                  call, it decrements the counter, and passes the call through
  6422.                  to GEM only if the counter has dropped back to zero.
  6423.  
  6424.                  A macro in GEMFAST.H automatically routes your exiting
  6425.                  wind_update() calls through wnd_update().  This is required
  6426.                  because all calls must go through this routine for the
  6427.                  stacked BEG/END system to work.
  6428.  
  6429.        Source:   aesfuncs\wndupdat.c
  6430.  
  6431.  
  6432.  
  6433.  
  6434.  
  6435.  
  6436.  
  6437.  
  6438.  
  6439.  
  6440.  
  6441.  
  6442.  
  6443.  
  6444.  
  6445.  
  6446.  
  6447.  
  6448.  
  6449.  
  6450.  
  6451.  
  6452.  
  6453.  
  6454.  
  6455.  
  6456.  
  6457.  
  6458.  
  6459.  
  6460.  
  6461.  
  6462.        
  6463.        ======================================================================
  6464.        GemFast v1.8                                                   Page 94
  6465.  
  6466.  
  6467.  
  6468.  
  6469.  
  6470.  
  6471.  
  6472.  
  6473.        Extended Binding Functions
  6474.  
  6475.  
  6476.                  The extended binding functions provide an alternate calling
  6477.                  format for some of the standard GEM functions.  For the most
  6478.                  part, the alternate standard allows you to pass a pointer to
  6479.                  a structure in place of the discreet parms accepted by the
  6480.                  corresponding GEM function.  This has several advantages,
  6481.                  including smaller faster code at runtime, and easier-to-read
  6482.                  source code.
  6483.  
  6484.                  These functions are all portable to compilers that have
  6485.                  their own (non-GemFast) low-level bindings.  
  6486.  
  6487.                  I would like to recommend that you use the envx_multi()
  6488.                  function instead of evnt_multi() in all your programs.  Get
  6489.                  used to working with the XMULTI structure it uses.  To be
  6490.                  quite frank, it's looking more and more like you'll be
  6491.                  required to use it in GemFast v2.0.
  6492.  
  6493.  
  6494.        int     evnx_multi(XMULTI *xm)
  6495.        ______________________________________________________________________
  6496.  
  6497.        Summary:  Call evnt_multi() passing just a single pointer.
  6498.  
  6499.        Input:    The xm parameter is a pointer to an XMULTI structure.
  6500.  
  6501.        Returns:  The mask of events which occurred; xm->mwhich.
  6502.  
  6503.        Details:  This function keeps all the input and output parms for an
  6504.                  evnt_multi() call in a single structure.  This is more
  6505.                  efficient than stacking and unstacking 50-some bytes of
  6506.                  parameters on each call, and it also allows you to "pass
  6507.                  off" event handling to a series of event handlers by passing
  6508.                  a single pointer to each handler.  GemFast 2.0 will make
  6509.                  heavy use of the latter technique.
  6510.  
  6511.  
  6512.  
  6513.  
  6514.  
  6515.  
  6516.  
  6517.  
  6518.  
  6519.  
  6520.  
  6521.  
  6522.  
  6523.  
  6524.  
  6525.  
  6526.  
  6527.  
  6528.        
  6529.        ======================================================================
  6530.        GemFast v1.8                                                   Page 95
  6531.  
  6532.  
  6533.  
  6534.  
  6535.  
  6536.  
  6537.  
  6538.  
  6539.                  The XMULTI structure is defined in GEMFAST.H, as follows:
  6540.  
  6541.                      typedef struct xmulti {
  6542.                          int     msgbuf[8];  /* Message buffer
  6543.                          int     mflags,     /* Mask of events to wait for */
  6544.                                  mbclicks,   /* Button clicks to wait for  */
  6545.                                  mbmask,     /* Which buttons to wait for  */
  6546.                                  mbstate,    /* Wait for button up/down    */
  6547.                                  mm1flags;   /* M1 event: wait for in/out  */
  6548.                          GRECT   mm1rect;    /* M1 event: coordinates      */
  6549.                          int     mm2flags;   /* M2 event: wait for in/out  */
  6550.                          GRECT   mm2rect;    /* M2 event: coordinates      */
  6551.                          int     mtlocount,  /* Timer count low            */
  6552.                                  mthicount;  /* Timer count high           */
  6553.                          int     mwhich,     /* Bitmap of occurred events  */
  6554.                                  mmox,       /* Mouse x at time of event   */
  6555.                                  mmoy,       /* Mouse y at time of event   */
  6556.                                  mmobutton,  /* Mouse buttons at event     */
  6557.                                  mmokstate,  /* Keystate (shift) at event  */
  6558.                                  mkreturn,   /* Key pressed                */
  6559.                                  mbreturn;   /* Mouse button click count   */
  6560.                      } XMULTI;
  6561.  
  6562.                  You can use the values in the XMULTI structure just as you
  6563.                  would use discreet variables with an evnt_multi() call.  
  6564.  
  6565.                  I would like to caution against a technique I've seen in
  6566.                  some programs:  don't compare the return value (or xm.mwhich
  6567.                  field) using the equality operator.  This field holds a
  6568.                  bitmap of events that occurred, and GEM *will* return
  6569.                  multiple events at once in some situations.  You should test
  6570.                  for each event type you expect using the & operator.  
  6571.  
  6572.                  I would like to recommend that you get used to using this
  6573.                  function, because the overwhelming likelihood is that you'll
  6574.                  have to use it in GemFast 2.0 for the library to work right.
  6575.  
  6576.        Source:   aesxbind.s\evnxmult.s
  6577.                  aesxbind.c\evnxmult.c
  6578.  
  6579.  
  6580.  
  6581.  
  6582.        int     frmx_center(OBJECT *ptree, GRECT *prect)
  6583.        ______________________________________________________________________
  6584.  
  6585.        Summary:  Call form_center() passing a single pointer for the return
  6586.                  values.
  6587.  
  6588.        Input:    The ptree parameter is a pointer to the object tree to be
  6589.                  centered.
  6590.  
  6591.                  The prect parameter is a pointer to a GRECT structure into
  6592.                  which the on-screen sizes of the dialog are returned.
  6593.  
  6594.        
  6595.        ======================================================================
  6596.        GemFast v1.8                                                   Page 96
  6597.  
  6598.  
  6599.  
  6600.  
  6601.  
  6602.  
  6603.  
  6604.  
  6605.        Returns:  TRUE (1) always.
  6606.  
  6607.        See Also: frm_sizes() 
  6608.  
  6609.        Details:  This function allows you to pass a single pointer to an
  6610.                  output rectangle, instead of the four pointers required by
  6611.                  the standard form_center() function.
  6612.  
  6613.        Source:   aesxbind.s\frmxcntr.s
  6614.                  aesxbind.c\frmxcntr.c
  6615.  
  6616.  
  6617.  
  6618.  
  6619.        int     frmx_dial(int action, GRECT *little, GRECT *big)
  6620.        ______________________________________________________________________
  6621.  
  6622.        Summary:  Call form_dial() passing pointers to the little and big
  6623.                  rectangles.
  6624.  
  6625.        Input:    The action parameter is the GEM-defined action flag.
  6626.  
  6627.                  The little parameter is a pointer to the small-size
  6628.                  rectangle used with the FMD_GROW and FMD_SHRINK action
  6629.                  flags.  Must not be NULL, but may point to a rectangle
  6630.                  containing all zeros.
  6631.  
  6632.                  The big parameter is a pointer to the big-size rectangle;
  6633.                  the rectangle the dialog will occupy on-screen.  Must not be
  6634.                  NULL.
  6635.  
  6636.        Returns:  TRUE (1) always.
  6637.  
  6638.        See Also:
  6639.  
  6640.        Details:  This function allows you to call form_dial() passing just
  6641.                  pointers to the two rectangles instead of passing all eight
  6642.                  rectangle fields as discreet values.
  6643.  
  6644.        Source:   aesxbind.s\frmxdial.s
  6645.                  aesxbind.c\frmxdial.c
  6646.  
  6647.  
  6648.  
  6649.  
  6650.        int     grfx_dragbox(GRECT *startrect, GRECT *boundrect,
  6651.                         GRECT *endrect)
  6652.        ______________________________________________________________________
  6653.  
  6654.        Summary:  Call graf_dragbox() passing just rectangle pointers.
  6655.  
  6656.        Input:    The startrect parameter is a pointer to the starting
  6657.                  location for the dragbox.
  6658.  
  6659.  
  6660.        
  6661.        ======================================================================
  6662.        GemFast v1.8                                                   Page 97
  6663.  
  6664.  
  6665.  
  6666.  
  6667.  
  6668.  
  6669.  
  6670.  
  6671.                  The boundrect parameter is a pointer to the rectangle
  6672.                  defining the boundary in which the ending rectangle is
  6673.                  confined.
  6674.  
  6675.                  The endrect parameter is a pointer to the rectangle which
  6676.                  will receive the results after the call.  This may point to
  6677.                  the same rectangle as startrect without any problems.
  6678.  
  6679.        Returns:  Non-zero on success, or zero on failure (per GEM).
  6680.  
  6681.        See Also:
  6682.  
  6683.        Details:  This function allows you to pass rectangle pointers instead
  6684.                  of discrete parameters to graf_dragbox().  In the most
  6685.                  common usage, the startrect and endrect parameters will be
  6686.                  the same, so that the rectangle is 'moved' by the dragbox
  6687.                  operation.  The width and height will never be changed by
  6688.                  this function, only the x and y.  You can often use the
  6689.                  global desktop rectangle variable (&gl_rwdesk) as the
  6690.                  boundrect parameter.
  6691.  
  6692.        Source:   aesxbind.s\grfxdrag.s
  6693.                  aesxbind.c\grfxdrag.c
  6694.  
  6695.  
  6696.  
  6697.  
  6698.        int     winx_calc(int type, int kind, GRECT inrect, GRECT *outrect)
  6699.        ______________________________________________________________________
  6700.  
  6701.        Summary:  Call wind_calc() passing a single pointer to the output.
  6702.  
  6703.        Input:    The type, kind, and inrect parameters are identical to the
  6704.                  corresponding wind_calc() parameters.
  6705.  
  6706.                  The outrect parameter is a pointer to the output rectangle
  6707.                  where the results of the calculation are stored.
  6708.  
  6709.        Returns:  Zero on error, or non-zero on success.
  6710.  
  6711.        See Also:
  6712.  
  6713.        Details:  Please note that the inrect parameter is a structure passed
  6714.                  by value (4 values stacked) not a pointer to a rectangle.
  6715.  
  6716.        Source:   aesxbind.s\winxcalc.s
  6717.                  aesxbind.c\winxcalc.c
  6718.  
  6719.  
  6720.  
  6721.  
  6722.  
  6723.  
  6724.  
  6725.  
  6726.        
  6727.        ======================================================================
  6728.        GemFast v1.8                                                   Page 98
  6729.  
  6730.  
  6731.  
  6732.  
  6733.  
  6734.  
  6735.  
  6736.  
  6737.        int     winx_get(int whandle, int field, GRECT *outrect)
  6738.        ______________________________________________________________________
  6739.  
  6740.        Summary:  Call wind_get() passing a single output pointer.
  6741.  
  6742.        Input:    The whandle and field parameters are identical to the
  6743.                  corresponding wind_get() parameters.
  6744.  
  6745.                  The outrect parameter is a pointer to the output rectangle
  6746.                  where the results of the query are stored.
  6747.  
  6748.        Returns:  Zero on error or non-zero on success.
  6749.  
  6750.        See Also:
  6751.  
  6752.        Details:  Please note that this function will always write 8 bytes of
  6753.                  output to the memory location indicated by outrect even if
  6754.                  the type of query you're doing normally returns less
  6755.                  information that.  (IE, don't use &integer_variable for this
  6756.                  parameter, or the memory following the integer variable will
  6757.                  be overwritten as well.)
  6758.  
  6759.        Source:   aesxbind.s\winxget.s
  6760.                  aesxbind.c\winxget.c
  6761.  
  6762.  
  6763.  
  6764.  
  6765.  
  6766.  
  6767.  
  6768.  
  6769.  
  6770.  
  6771.  
  6772.  
  6773.  
  6774.  
  6775.  
  6776.  
  6777.  
  6778.  
  6779.  
  6780.  
  6781.  
  6782.  
  6783.  
  6784.  
  6785.  
  6786.  
  6787.  
  6788.  
  6789.  
  6790.  
  6791.  
  6792.        
  6793.        ======================================================================
  6794.        GemFast v1.8                                                   Page 99
  6795.  
  6796.  
  6797.  
  6798.  
  6799.  
  6800.  
  6801.  
  6802.  
  6803.        Extended VDI Functions
  6804.  
  6805.  
  6806.                  The extended VDI functions provide several functions not
  6807.                  documented in standard VDI reference manuals.
  6808.  
  6809.  
  6810.  
  6811.  
  6812.        int    vdicall(int *control, int *intin, int *ptsin, int *intout,
  6813.                       int *ptsout)
  6814.        ______________________________________________________________________
  6815.  
  6816.        Summary:  Direct call to VDI with caller-specified structures/arrays.
  6817.  
  6818.        Input:    All input parameters are pointers to arrays of int.  See
  6819.                  your VDI documentation for details on each of the arrays.
  6820.  
  6821.        Returns:  The contents of intout[0].
  6822.  
  6823.        Details:  This function allows you to call VDI functions not directly
  6824.                  supported by the VDIFAST.A library.  Within your program,
  6825.                  you set up arrays containing the parameters for the
  6826.                  function, and then pass pointers to those arrays to this
  6827.                  routine.  It will combine the pointers into a VDI parameter
  6828.                  block, and issue the VDI trap.
  6829.  
  6830.                  You must always supply a non-NULL pointer for control, and
  6831.                  the values in control must contain everything VDI needs to
  6832.                  process the call.  (IE, opcode, sub-opcode if needed, intin
  6833.                  count, ptsin count, and extended control info such as the
  6834.                  FDB pointers for a blit, if needed.)  You never need to
  6835.                  supply the intout or ptsout count values in the control
  6836.                  array; VDI will fill those in (and will ignore anything you
  6837.                  put there anyway).
  6838.  
  6839.                  The other array pointers may be NULL if they are not needed
  6840.                  for a given VDI call.  (If there are no ptsin parms for the
  6841.                  call, just code NULL for the ptsin parameter.)  The intout
  6842.                  array is handled specially: if you supply a NULL intout
  6843.                  pointer, the vdicall() routine allocates a 256-byte intout
  6844.                  array on the stack for you.  It returns the value from
  6845.                  intout[0] as the function return value, and discards the
  6846.                  rest of the array.  This is mainly to provide ease-of-use in
  6847.                  coding custom bindings which only need a single-word return
  6848.                  value.
  6849.  
  6850.        Source:   vdibind\vdicall.s
  6851.  
  6852.  
  6853.  
  6854.        int     vgd_detect(void)
  6855.        ______________________________________________________________________
  6856.  
  6857.  
  6858.        
  6859.        ======================================================================
  6860.        GemFast v1.8                                                  Page 100
  6861.  
  6862.  
  6863.  
  6864.  
  6865.  
  6866.  
  6867.  
  6868.  
  6869.        Summary:  Detect presence of GDOS on system.
  6870.  
  6871.        Input:    None.
  6872.  
  6873.        Returns:  Non-zero if GDOS is present, or zero if it is not.
  6874.  
  6875.        Details:  This function calls trap #2 with -2L in register D0.  If the
  6876.                  -2 is still in D0 on return, GDOS is not present, and zero
  6877.                  is returned.  Otherwise, a non-zero value is returned, to
  6878.                  indicate that GDOS services are available.
  6879.  
  6880.        Source:   vdibind\vgdetect.s
  6881.  
  6882.  
  6883.  
  6884.  
  6885.        void    v_gchar(int vdi_handle, int x, int y, char outchar)
  6886.        ______________________________________________________________________
  6887.  
  6888.        Summary:  Output a single character.
  6889.  
  6890.        Input:    The vdi_handle parameter is the handle of the VDI
  6891.                  workstation.
  6892.  
  6893.                  The x and y parameters are the coordinates at which the
  6894.                  character is placed.
  6895.  
  6896.                  The outchar parameter is the character to output.
  6897.  
  6898.        Returns:  Nothing.
  6899.  
  6900.        Details:  This function writes a single character to the screen.  It
  6901.                  requires less setup than the standard v_gtext() function,
  6902.                  and is a bit faster and easier to use.
  6903.  
  6904.        Source:   vdibind\vgchar.s
  6905.  
  6906.  
  6907.  
  6908.  
  6909.  
  6910.  
  6911.  
  6912.  
  6913.  
  6914.  
  6915.  
  6916.  
  6917.  
  6918.  
  6919.  
  6920.  
  6921.  
  6922.  
  6923.  
  6924.        
  6925.        ======================================================================
  6926.        GemFast v1.8                                                  Page 101
  6927.  
  6928.  
  6929.  
  6930.  
  6931.